DOCSEARCHbyAlgolia
Submit Docs

nearcore Documentation

repository·master·Indexed 25 days ago

https://github.com/near/nearcore

The reference implementation of the NEAR Protocol, providing core blockchain infrastructure for server-less applications and smart contracts. This documentation covers the setup and execution of continuous, sharded, and synthetic benchmarks, including the use of the DB tool, Diesel migrations, and Forknet deployments on Google Cloud.

Tokens
194.2K
Snippets
241
Records
1K
Agent score
82%

What's inside nearcore

  1. Overview of NEAR Protocol and Developer Tools

    master

    NEAR Protocol is the reference implementation of the NEAR Protocol, providing infrastructure for server-less applications and smart contracts. It is designed for usability and scalability, aiming to provide PaaS-like experiences for developers.

    To build on NEAR, you can use the following tools:

    • JS Client library: Connect to the NEAR Protocol from applications (near-api-js).
    • Smart Contract SDKs: Write smart contracts and stateful server-less functions using Rust or JavaScript/TypeScript.
    • Documentation & Tutorials: Access official documentation, tutorials, and API docs.
    • Formal Specification: Refer to the Nomicon for the NEAR Protocol formal specification and developer guides.

  2. Overview of NEAR RPC Servers

    master

    The NEAR protocol provides two primary RPC server interfaces for interacting with the blockchain:

    1. JSON-RPC Server: The primary node interface, typically running on port 3030. It supports core blockchain operations, status checks, and light client endpoints (e.g., next_light_client_block, light_client_proof) for trustless verification.
    2. Rosetta RPC Server: A specialized server running on port 3040 that provides compatibility with the Rosetta API, primarily used by exchanges.

    Both servers communicate with internal backend actors (ClientActor, ViewClientActor, RpcHandlerActor) via asynchronous message passing.

  3. Overview of Near Telemetry

    master

    Near Telemetry is a utility (TelemetryActor) used by nearcore binaries (such as validators and RPC nodes) to transmit metrics information. It sends telemetry data as JSON via HTTP POST requests to a predefined list of servers.

    To enable telemetry, the specific nearcore binary must be configured to do so within its config.json file.

  4. Overview of NEAR Action types

    master

    In NEAR, transactions consist of a list of actions to be performed on the receiver_id side. The core Action enum defines the following available operations:

    • CreateAccount(CreateAccountAction)
    • DeployContract(DeployContractAction)
    • FunctionCall(FunctionCallAction)
    • Transfer(TransferAction)
    • Stake(StakeAction)
    • AddKey(AddKeyAction)
    • DeleteKey(DeleteKeyAction)
    • DeleteAccount(DeleteAccountAction)
    • Delegate(SignedDelegateAction)
    • DeployGlobalContract(DeployGlobalContractAction)
    • UseGlobalContract(UseGlobalContractAction)
    • DeterministicStateInit(DeterministicStateInitAction)

    For several actions, the predecessor_id and receiver_id must be equal:

    • DeployContract
    • Stake
    • AddKey
    • DeleteKey
    • DeleteAccount

    Note on Account Creation: If CreateAccount is the first action in a list, the predecessor_id becomes the receiver_id for all subsequent actions until a DeleteAccount action is encountered. This allows the newly created account to perform subsequent actions (like adding keys) immediately.

    pub enum Action {
    CreateAccount(CreateAccountAction),
    DeployContract(DeployContractAction),
    FunctionCall(FunctionCallAction),
    Transfer(TransferAction),
    Stake(StakeAction),
    AddKey(AddKeyAction),
    DeleteKey(DeleteKeyAction),
    DeleteAccount(DeleteAccountAction),
    Delegate(SignedDelegateAction),
    DeployGlobalContract(DeployGlobalContractAction),
    UseGlobalContract(UseGlobalContractAction),
    DeterministicStateInit(DeterministicStateInitAction),
}

  5. Overview of the Runtime Parameter Estimator

    master

    The Runtime Parameter Estimator is a byzantine benchmarking suite used to validate NEAR Protocol gas parameters. It measures performance under worst-case scenarios, assuming up to one-third of validators and all users collude to slow the system.

    Goal: Ensure that gas parameters are set such that a chunk filled with 1 Pgas (Peta gas) takes at most 1 second to apply, or more generally, that 1 Tgas of execution consumes no more than 1ms of wall-clock time.

    Location: The source code is located in the runtime/runtime-params-estimator directory of the nearcore repository.

  6. Overview of the fmt crate

    master
    The fmt crate provides a lightweight collection of wrapper types used for pretty-printing values within the nearcore codebase. It is designed to keep dependencies to an absolute minimum because it is a dependency of near-primitives, which is widely used across various NEAR-related crates both inside and outside the nearcore repository.

  7. Overview of Post-Quantum Signatures (ML-DSA-65) in NEAR

    master

    NEAR supports ML-DSA-65 (FIPS 204) as a third transaction-signature scheme alongside ed25519 and secp256k1. This integration is active once the PostQuantumSignatures protocol feature is enabled (stabilized at protocol version 85).

    Scope of Support:

    • Supported: Transaction signing and access keys.
    • Not Supported: Validator keys, block/chunk signatures, host-function verification primitives, and implicit-account derivation.

    ML-DSA-65 Specifications:

    • Public Key Size: 1952 bytes
    • Signature Size: 3309 bytes
    • Raw Private Key Size: 4032 bytes

  8. Overview of Near Custom Tracing architecture

    master

    The custom tracing setup for NEAR nodes enables distributed tracing and visualization through the following pipeline:

    1. Trace Generation: NEAR nodes are configured to send OpenTelemetry traces to the near-tracing collector.
    2. Storage: The near-tracing collector stores these traces in a MongoDB instance.
    3. Querying: The near-tracing querier (included in the same crate) accepts time interval queries and retrieves the corresponding tracing data.
    4. Visualization: The retrieved data is returned in a Firefox profile format, which can be visualized using a forked version of the Firefox profiler.

  9. Overview of Genesis Tools

    master

    Genesis Tools provides utilities for managing and simulating the initial state of the NEAR Protocol. The current toolset includes:

    • genesis-populate: A tool for creating a genesis state dump populated with a large number of accounts to simulate realistic trie complexity.
    • genesis-rebase (Planned): A tool for rebasing the entire chain to a new genesis.
    • genesis-mainnet (Planned): A tool for creating the main genesis used at the mainnet launch.

  11. Overview of the Storage delta calculator

    master

    The Storage delta calculator is a utility designed to compare actual storage usage against the usage values saved within the state. It serves as a sanity check for updates, as storage usage directly impacts the amount of tokens locked in user accounts.

    WARNING: This tool was built for a specific migration in May 2021 and is no longer maintained.

  12. Overview of near-chunks and Chunk Handling

    master

    The near-chunks crate manages the handling of chunks within the NEAR protocol. In NEAR, a block consists of multiple chunks (at most one per shard). To ensure data availability, chunk contents are encoded using Reed Solomon encoding (ErasureCoding), creating PartialEncodedChunks.

    Validators receive a subset of these partial chunks. An honest validator only approves a block if it has received enough parts to satisfy has_all_parts() for every chunk in the block.

    Node Requirements for Block Acceptance:

    • For shards the node tracks: The node must possess the full chunk. It achieves this by receiving the required number of PartialChunks (specifically data_shard_count, which is less than total_shard_count) to reconstruct the chunk and persist it in local storage.
    • For shards the node does not track: The node must have the receipts from that shard to all other shards.