Skip to content

Commit cdac155

Browse files
committed
docs(protocol): fix image placements, add missing notarization diagram, restore per-layer description
Consensus: - Move consensus_orders_messages diagram to ## Consensus rounds (correct position per Learn Hub: after the crypto-finality section, not before it) - Restore the high-level three-phase overview bullets (block making, notarization, finalization) before the detailed subsections, matching the original orientation paragraph - Add missing consensus_notarization diagram after the notarization paragraph about higher-rank fallback - Update all image alt text to match original Learn Hub captions State synchronization: - Move state-sync diagram from after the opening paragraph to the end of ## Recovering nodes, where it was in the Learn Hub ("Nodes that are behind" section shows the diff-based incremental sync, which the image illustrates) Protocol Stack overview: - Add per-layer description paragraph after the diagram (present in the Learn Hub "Blockchain Protocol" article, omitted in our first draft)
1 parent 279f9ef commit cdac155

4 files changed

Lines changed: 17 additions & 9 deletions

File tree

docs/concepts/protocol/consensus.md

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ sidebar:
77

88
The consensus protocol allows every node in a subnet to agree on which messages to process and in what order. Each subnet runs its own independent instance of the protocol. The output of each consensus round is a single finalized block of ordered messages that every node then executes deterministically, producing the same state transition on each.
99

10-
![Consensus collects ingress messages, XNet messages, and protocol messages into an ordered block](/concepts/protocol/consensus_orders_messages.webp)
11-
1210
ICP's consensus is designed to meet three requirements:
1311

1412
- **Low latency.** Blocks are finalized in roughly one second, achieving near-instant finality.
@@ -17,32 +15,40 @@ ICP's consensus is designed to meet three requirements:
1715

1816
## Cryptographic finality
1917

20-
ICP provides cryptographic finality rather than probabilistic finality. Probabilistic finality considers a block final only after enough subsequent blocks have built on top of it. ICP avoids this approach for two reasons: probabilistic finality is a weak guarantee, and it would substantially increase the time before a message response can be trusted.
18+
ICP provides cryptographic finality rather than probabilistic finality. Probabilistic finality considers a block final only after enough subsequent blocks have built on top of it. ICP avoids this approach for two reasons: probabilistic finality is a very weak guarantee, and it would substantially increase the time before a message response can be trusted.
2119

2220
The ICP consensus protocol achieves cryptographic finality while making minimal assumptions about the network. Safety does not depend on any bound on message delivery time (the protocol only assumes an asynchronous network). For a globally distributed network, synchrony is not a realistic assumption. When messages do arrive promptly, the protocol makes progress with good latency. Correctness is always guaranteed regardless of message delays, as long as fewer than one third of subnet nodes are faulty.
2321

2422
## Consensus rounds
2523

24+
![Consensus round yields an ordered sequence of messages](/concepts/protocol/consensus_orders_messages.webp)
25+
2626
The protocol maintains a tree of notarized blocks, with a special genesis block at the root. The protocol proceeds in rounds. Each round adds at least one new notarized block to the tree as a child of a notarized block from the previous round. When things proceed normally, exactly one notarized block is added and it is immediately finalized. Once a block is finalized, all of its ancestors are implicitly finalized. The protocol guarantees a unique chain of finalized blocks. This chain is the output of consensus.
2727

28-
A consensus round has three phases.
28+
At a high level, each round has three phases:
29+
30+
- **Block making.** At least one node (the block maker) proposes a block by broadcasting it to all nodes in the subnet. When things go right there is only one block maker, but sometimes there may be several.
31+
- **Notarization.** For a block to become notarized, at least two thirds of the nodes must validate and support its notarization.
32+
- **Finalization.** For a block to become finalized, at least two thirds of the nodes must support its finalization. A node supports finalization only if it did not support notarization of any other block in that round, which guarantees that a finalized block has no competing notarized block.
2933

3034
### Block making
3135

32-
In every round, one or more nodes called [block makers](../../references/glossary.md#block-maker) propose a block. Each block contains a reference to a notarized block from the previous round, ingress messages submitted by users, and XNet messages received from other subnets.
36+
In every round, one or more nodes called [block makers](../../references/glossary.md#block-maker) propose a block. Each block contains a reference to a notarized block from the previous round, ingress messages submitted by users (received directly or via P2P from other nodes), and XNet messages received from other subnets.
3337

3438
Block makers are selected through a random permutation of subnet nodes, using randomness derived from a [random beacon](../../references/glossary.md#random-beacon) produced by [chain-key cryptography](../chain-key-cryptography.md). The permutation assigns a rank to each node. The lowest-rank node acts as the primary block maker and broadcasts its proposal to all subnet nodes.
3539

3640
If the primary block maker is faulty or the network is slow and no notarized block appears within a timeout, nodes of increasing rank step in to propose blocks. The protocol guarantees that one block eventually gets notarized in every round.
3741

38-
![Block maker selection: the lowest-rank node proposes first; higher-rank nodes step in on timeout](/concepts/protocol/block_maker.webp)
42+
![Block maker constructs a new block and broadcasts it to the subnet](/concepts/protocol/block_maker.webp)
3943

4044
### Notarization
4145

4246
When a node receives a block proposal, it validates it for syntactic correctness. If valid, the node broadcasts the block along with a notarization share: a BLS multi-signature share. A block becomes notarized when at least two thirds of subnet nodes have submitted notarization shares for it. These shares can be aggregated into a compact notarization.
4347

4448
If the primary block maker's proposal is notarized within the timeout, a node will not support the notarization of any other block in that round. Otherwise, a node may support notarization of blocks from higher-rank block makers (but only up to the highest rank it has already committed to).
4549

50+
![Notarization support of increasing-rank block proposals in a round](/concepts/protocol/consensus_notarization.webp)
51+
4652
### Finalization
4753

4854
Once a node obtains a notarized block, it will not subsequently support notarization of any other block in that round. If the node had not previously supported notarization of any other block, it also broadcasts a finalization share for this block. A block is finalized when at least two thirds of nodes have submitted finalization shares.

docs/concepts/protocol/index.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ Each node runs a replica process structured in four layers:
1616
3. [Message routing](message-routing.md): delivery of messages to canister input queues and state certification
1717
4. [Execution](execution.md): deterministic execution of canister code
1818

19-
![The four layers of the ICP protocol stack: peer-to-peer, consensus, message routing, and execution](/concepts/protocol/core_protocol_layers.webp)
19+
![4-layer architecture of the Internet Computer](/concepts/protocol/core_protocol_layers.webp)
20+
21+
The **peer-to-peer** layer accepts messages from users and exchanges messages between nodes. The **consensus** layer makes all nodes agree on which messages to process and in what order. The **message routing** layer picks up finalized blocks from consensus and routes messages to the appropriate canisters. The **execution** layer deterministically executes canister code on those messages.
2022

2123
The lower two layers (peer-to-peer and consensus) are responsible for agreeing, each round, on a block of messages. The upper two layers (message routing and execution) deterministically process that block on every node.
2224

docs/concepts/protocol/state-synchronization.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ sidebar:
77

88
State synchronization allows nodes to join a running subnet or recover from downtime without replaying every message ever executed. Instead, the protocol creates periodic certified checkpoints that capture a complete snapshot of the subnet state. A node that needs to catch up downloads a recent checkpoint and replays only the blocks produced since that checkpoint.
99

10-
![State synchronization: a catching-up node downloads a certified checkpoint then replays only recent blocks](/concepts/protocol/state-sync.webp)
11-
1210
Checkpoints are certified by the subnet through a signature over a Merkle-tree manifest (see [Message routing: per-checkpoint certification](message-routing.md#per-checkpoint-certification)). They are made available to other nodes via the [peer-to-peer layer](peer-to-peer.md) as part of a [**catch-up package**](../../references/glossary.md#catch-up-package-cup).
1311

1412
## Joining nodes
@@ -27,6 +25,8 @@ The subnet state is organized as a Merkle tree and can reach up to a terabyte in
2725

2826
This incremental approach ensures that a recovering node transfers the minimum amount of data needed to rejoin the subnet, rather than downloading the full state again.
2927

28+
![The catching-up replica only syncs the parts of the replicated state that differ from the up-to-date replica](/concepts/protocol/state-sync.webp)
29+
3030
## Further reading
3131

3232
- [Message routing](message-routing.md): how checkpoints and state certification work
20.9 KB
Loading

0 commit comments

Comments
 (0)