Skip to content

Commit

Permalink
doc: update architecture.md (#4334)
Browse files Browse the repository at this point in the history
Update `architecture.md` to include some high-level information about nearcore and two ways state updates can happen. Also add codeowners for `/docs`.

Test plan
---------
N/A
  • Loading branch information
bowenwang1996 authored Jun 21, 2021
1 parent e76004d commit 87776be
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 0 deletions.
2 changes: 2 additions & 0 deletions CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,5 @@

/.buildkite/ @chefsale @mhalambek
/scripts/ @chefsale @mhalambek

/docs/ @bowenwang1996 @matklad
20 changes: 20 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,17 @@ More specifically, the neard binary can do the following:
- generate files necessary to start a node
- start a node with a given folder that contains required data

There are three major components of nearcore:

- Network. We implement a peer-to-peer network that powers communications between blockchain nodes.
This includes initiating connections with other nodes, maintain a view of the entire network, routing messages to the right nodes, etc.
Network is a somewhat standalone module, though it uses information about validators to propagate and validate certain messages.
- Chain. Chain is responsible for building and maintaining the blockchain data structure.
This includes block and chunk production and processing, consensus, and validator selection.
However, chain is not responsible for actually applying transactions and receipts.
- Runtime. Runtime is the execution engine that actually applies transactions and receipts and performs state transitions.
This also includes compilation of contracts (wasm binaries) and execution of contract calls.

## Entry Points

`nearcore/src/main.rs` contains the main function that starts a blockchain node.
Expand Down Expand Up @@ -49,6 +60,15 @@ This crate contains most of the chain logic (consensus, block processing, etc).
**Architecture Invariant**: interface between chain and runtime is defined by `RuntimeAdapter`.
All invocations of runtime goes through `RuntimeAdapter`

**State update**

The blockchain state can be changed in the following two ways:
- Applying a chunk. This is how the state is normally updated: through `Runtime::apply`.
- State sync. State sync can happen in two cases:
* A node is far enough behind the most recent block and triggers state sync to fast forward to the state of a very recent block without having to apply blocks in the middle.
* A node is about to become validator for some shard in the next epoch, but it does not yet have the state for that shard.
In this case, it would run state sync through the `catchup` routine.

### `chain/chunks`

This crate contains most of the sharding logic which includes chunk creation, distribution, and processing.
Expand Down

0 comments on commit 87776be

Please sign in to comment.