DOCSEARCHbyAlgolia
Submit Docs

Nomicon: NEAR Protocol Technical Documentation

website·Indexed 33 days ago

https://nomicon.io/

Technical documentation and architecture guides for the NEAR Protocol and nearcore. Covers core components including the Blockchain Layer, Network Specification, Runtime Specification, gas profiles, transaction routing, cross-shard transactions, and the Merkle-Patricia Trie storage system.

Tokens
131.4K
Snippets
436
Records
887
Agent score
68%

What's inside Nomicon

  2. Overview of the nearcore development guide

    The nearcore development guide is intended for developers working on the nearcore codebase itself. It is organized into four primary sections:

    • Protocol Specification: Formal specifications for the chain, network, and runtime defining the NEAR Protocol blockchain.
    • Architecture: Explanations of how the code works, including system flows (e.g., transaction flow).
    • Practices: Guidelines on code style, issue tracking, and performance debugging.
    • Misc: General documentation and assorted technical notes.

    For those starting out, it is recommended to begin with the Architecture Overview and the guide on how to run a node.

  3. Overview of the Runtime crate

    The Runtime crate encapsulates the logic for handling transactions and receipts. It processes account-level actions (like account creation) in-place, but delegates smart contract calls to the near-vm-runner.

  4. Overview of the nearcore development guide

    The nearcore development guide is intended specifically for developers contributing to the nearcore codebase. It is hosted at https://nomicon.io/ and is built from sources in the nearcore GitHub repository. For NEAR users, contract developers, or validator node operators, the official user documentation is located at https://docs.near.org.

  5. Overview of synthetic workload benchmarking

    Synthetic benchmarking involves starting a new network with an empty state, creating a controlled state, and generating transactions against that state. This allows for fine-grained control over traffic intensity and performance comparison across different neard versions or features without the noise of real-world traffic. The tooling is located in benchmarks/synth-bm.

  6. Overview of the Runtime Parameter Estimator

    The Runtime Parameter Estimator is a benchmarking suite used to verify that gas parameters defined in the protocol are correct. The goal is to ensure that a chunk filled with 1 Pgas (Peta gas) takes at most 1 second to be applied, or more generally, that 1 Tgas of execution consumes no more than 1ms of wall-clock time. It employs 'byzantine benchmarking,' which assumes that up to a third of validators and all users collude to make the system as slow as possible.

  7. Overview of state dumping for archival

    Nodes can dump the state of every epoch to external storage (Local filesystem, GCS, or S3) for archival and state-distribution tooling. Note that centralized state sync (consuming state parts from external storage) has been removed; nodes now sync state exclusively from peers.

  8. Overview of NEAR Block and Chunk Producers

    NEAR utilizes two types of producers to balance decentralization and security during its 'Simple Nightshade' phase:

    • Block Producers: Track all shards, validate all transactions, and produce blocks. They are a subset of chunk producers.
    • Chunk-only Producers: Track only a single shard and produce chunks. They never produce blocks.

    Selection is based on stake: larger stakes are preferred, and the frequency of selection is proportional to the participant's stake. All selected producers are intended to produce at least one chunk/block per epoch.

  9. Overview of NEAR Action types

    NEAR transactions consist of a list of actions performed on a receiver_id. These actions are converted to receipts during processing. For several actions—specifically DeployContract, Stake, AddKey, DeleteKey, and DeleteAccount—the predecessor_id and receiver_id must be equal.

    Special Case: If the first action in a list is CreateAccount, the predecessor_id becomes the receiver_id for all subsequent actions until DeleteAccount, allowing a creator account to act on the newly created account.

    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),
}

  10. Overview of NEAR Action types

    In NEAR, transactions consist of a list of actions performed on the receiver_id side. These actions are converted to receipts during processing. For certain actions—specifically DeployContract, Stake, AddKey, DeleteKey, and DeleteAccount—the predecessor_id and receiver_id must be equal.

    Special Case: If the first action in a list is CreateAccount, the predecessor_id becomes the receiver_id for all subsequent actions until DeleteAccount is encountered, allowing a creator account to perform initial setup on the new account.

    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),
}

  11. Overview of NEAR Meta Transactions (NEP-366)

    Meta transactions (introduced in NEP-366) allow users to execute actions on the NEAR Protocol without owning gas or tokens. This is achieved by constructing and signing a DelegateAction off-chain. A third party, known as a relayer, submits this signed action as part of a standard transaction, paying the required gas fees on behalf of the user. The protocol verifies the user's signature and nonce before executing the inner actions, ensuring that the predecessor_id remains the original user.

  12. Overview of Routing Table Exchange Algorithm

    The Routing Graph Reconciliation algorithm uses Inverse Bloom Filters (IBF) to synchronize routing tables between two nodes (A and B) by exchanging only the edges that differ between them. This partial synchronization reduces bandwidth and CPU overhead. The algorithm uses IBFs with sizes ranging from $2^{10}$ to $2^{17}$, allowing the recovery of approximately $2^{17} / 1.3$ edges with 99% probability. If partial synchronization fails, the system falls back to a full routing table exchange.