docs: add protocol stack concept pages (Batch 1)#209
Merged
marc0olo merged 15 commits intoinfra/learn-hub-migration-prepfrom May 8, 2026
Merged
docs: add protocol stack concept pages (Batch 1)#209marc0olo merged 15 commits intoinfra/learn-hub-migration-prepfrom
marc0olo merged 15 commits intoinfra/learn-hub-migration-prepfrom
Conversation
Member
Author
|
Review notes The structure, content, and internal links all look good. One issue needs to be fixed before merge: Em-dashes (banned per CLAUDE.md): All 6 new files use em-dashes ( No other issues: frontmatter complete on all pages, all internal links resolve, |
This was referenced May 6, 2026
Member
Author
Review feedback1. Em-dashes (16 instances across 6 files)Em-dashes are banned project-wide per CLAUDE.md. Replace all
2. Terminology mismatch in
|
Member
Author
|
Feedback addressed:
|
marc0olo
added a commit
that referenced
this pull request
May 6, 2026
…ers pages - Fix AccountIdentifier em-dash in token-ledgers.md - Revert chain-fusion/ subdirectory links to chain-fusion.md (flat page on main) until PR #213 merges; affects token-ledgers.md and concepts/index.md - Remove broken link to protocol/execution.md#deterministic-time-slicing in cycles.md until PR #209 merges
Member
Author
|
Brand voice audit applied. The following fixes were committed in eb66cd9: Fixed automatically:
Open items for human review (no code change made):
|
marc0olo
force-pushed
the
infra/learn-hub-migration-prep
branch
from
dabad66 to
d191270
Compare
…ng, execution, state sync) Migrates 6 Learn Hub articles from the "Blockchain Protocol" section into docs/concepts/protocol/: index, consensus, peer-to-peer, message-routing, execution, and state-synchronization. Updates cross-links in network-overview.md and glossary.md to point to the new internal pages instead of learn.internetcomputer.org.
All em-dashes in Further reading bullets and numbered list items replaced with colons per project style rules. "The blockchain state" corrected to "The subnet state" in state-synchronization.md for terminology consistency.
…minology - protocol/index.md: drop "utility token" framing and blockchain analogy sentence - consensus.md: remove Bitcoin-like protocols comparison; reframe probabilistic finality - execution.md: remove "reverse gas model" from description and body; reframe canister-pays model; drop "traditional blockchains" comparison; replace "decentralized autonomous organization" with "community-governed application"
…urrence New glossary entries: block maker, Deterministic Time Slicing (DTS), orthogonal persistence, random beacon, Trusted Execution Environment (TEE), XNet Per-page link fixes: - consensus.md: link block maker and random beacon to new glossary entries - peer-to-peer.md: link NNS to glossary on first use - message-routing.md: link ingress messages, XNet, induction pool, NNS, catch-up package to glossary - execution.md: link cycles and query to glossary; link orthogonal persistence to its concept page - state-synchronization.md: link catch-up package to glossary
marc0olo
force-pushed
the
docs/concepts-protocol-stack
branch
from
568de86 to
97a5efd
Compare
marc0olo
added a commit
that referenced
this pull request
May 8, 2026
…ers pages - Fix AccountIdentifier em-dash in token-ledgers.md - Revert chain-fusion/ subdirectory links to chain-fusion.md (flat page on main) until PR #213 merges; affects token-ledgers.md and concepts/index.md - Remove broken link to protocol/execution.md#deterministic-time-slicing in cycles.md until PR #209 merges
4 tasks
…main /docs paths; remove em-dashes from dashboard API reference
- Convert Concepts from autogenerate to explicit items so subdirectory groups get proper labels: "Protocol Stack" and "Chain Fusion" instead of lowercase directory names - Protocol Stack index page now appears first in the group, leaf pages follow in layer order (peer-to-peer → performance) - Fix Further reading order in protocol/index.md to match sidebar order - Trim redundant four-phase consensus detail from network-overview.md; the full breakdown lives in concepts/protocol/consensus.md now - Add cross-reference to protocol/index.md in network-overview.md Nodes section where the four-layer stack is first named - Add Protocol Stack entry to concepts/index.md Architecture section
…nd synthetic latency - Add latency distribution screenshot (HTTP gateway observations, July 2025) and latency-vs-throughput graph (counter canister experiment, June 2025) sourced from the Learn Hub article and stored in public/concepts/protocol/ - Link each mainnet metric value to the exact timestamped API call that produced it, matching the original Learn Hub approach - Split Synthetic benchmarks into Throughput and Latency under load subsections; add the three latency data points (2.27s / 1.08s / 0.52s) and the experiment setup note (same-DC, 30ms simulated RTT) - Restore the full 12-city inter-datacenter RTT matrix (September 2023) replacing the prose summary; keep the three summary sentences below the table for quick orientation
…ex as Overview - Protocol Stack group now sits after App Architecture (matching the Architecture grouping in concepts/index.md) instead of at the end - Index pages within Protocol Stack and Chain Fusion groups now carry label "Overview" to avoid duplicate "Protocol Stack" / "Chain Fusion" entries in the subnav
…nsus, and state sync - core_protocol_layers.webp: four-layer stack diagram, placed after the numbered list in the Protocol Stack overview - consensus_orders_messages.webp: shows consensus collecting ingress, XNet, and protocol messages into an ordered block; placed after the opening paragraph in Consensus - block_maker.webp: rank-based block maker selection diagram; placed at the end of the Block making subsection before Notarization - state-sync.webp: checkpoint download and replay diagram; placed after the opening paragraph in State Synchronization
…m, 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)
4 tasks
…mance staging file migrated Adds "per canister" to the 2B per-round DTS limit in execution.md to distinguish it from the 8B/s subnet-level throughput figure on performance.md. Removes the out-of-scope performance staging file now that its content has been migrated.
marc0olo
added a commit
that referenced
this pull request
May 8, 2026
…urther reading link Adds node-infrastructure after app-architecture in the explicit Concepts sidebar (now that PR #209 has merged). Restores the Protocol Stack further reading link that was blocked during cross-branch validation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/concepts/protocol/subdirectory with 7 new concept pages: protocol stack overview, peer-to-peer, consensus, message routing, execution, state synchronization, and performancecore_protocol_layers,consensus_orders_messages,block_maker,consensus_notarization,state-sync; adds 2 performance screenshots from the Learn Hubautogenerateto explicititemsarray to fix lowercase group labels and control ordering; moves Protocol Stack after architecture pages; adds Chain Fusion and Protocol Stack index slugs labeled "Overview" to avoid duplicate group/child labelsdocs/concepts/index.md: adds Protocol Stack to Architecture sectiondocs/concepts/network-overview.md: trims consensus subsection (detail now in consensus.md), links to protocol stack overviewStaging files deleted
.migration/learn-hub/how-does-icp-work/blockchain-protocol/blockchain-protocol.md→docs/concepts/protocol/index.md.migration/learn-hub/how-does-icp-work/blockchain-protocol/consensus.md→docs/concepts/protocol/consensus.md.migration/learn-hub/how-does-icp-work/blockchain-protocol/peer-to-peer.md→docs/concepts/protocol/peer-to-peer.md.migration/learn-hub/how-does-icp-work/blockchain-protocol/message-routing.md→docs/concepts/protocol/message-routing.md.migration/learn-hub/how-does-icp-work/blockchain-protocol/execution-layer.md→docs/concepts/protocol/execution.md.migration/learn-hub/how-does-icp-work/blockchain-protocol/state-synchronization.md→docs/concepts/protocol/state-synchronization.md.migration/learn-hub/out-of-scope/what-is-icp/performance.md→docs/concepts/protocol/performance.mdSync recommendation
hand-written