Skip to content

docs: cryptography deep dives#214

Open
marc0olo wants to merge 2 commits intoinfra/learn-hub-migration-prepfrom
docs/concepts-cryptography-deep-dives
Open

docs: cryptography deep dives#214
marc0olo wants to merge 2 commits intoinfra/learn-hub-migration-prepfrom
docs/concepts-cryptography-deep-dives

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented May 6, 2026

Summary

  • Adds docs/concepts/certified-data.md — new concept page explaining: the verification problem (compare to Bitcoin SPV / Ethereum light clients), how ICP's single root public key enables chain-wide certificate verification, the certified state tree mechanism, certified variables interface, and applications (certified assets, Internet Identity)
  • Expands docs/concepts/chain-key-cryptography.md — adds context on why threshold ECDSA is significantly harder to implement than threshold BLS (asynchronous network requirement, robustness against 1/3 faulty nodes, protocol papers); notes that Schnorr/Ed25519 protocols are simplified variants with the same properties
  • Updates docs/concepts/index.md — adds certified-data.md entry in the cryptography section
  • Updates docs/guides/backends/certified-variables.md — links to the new concept page for background
  • Deletes all 4 staging files from .migration/learn-hub/.../chain-key-cryptography/

Sync recommendation

informed by learn hub staging files — chain-key-cryptography section

Add docs/concepts/certified-data.md covering the certified query
response mechanism: single public key verification, certified state
tree, certified variables interface, and applications (certified
assets, Internet Identity).

Expand docs/concepts/chain-key-cryptography.md with context on why
threshold ECDSA is harder than BLS (asynchronous network, robustness
requirements, protocol papers) and how Schnorr/EdDSA protocols are
simplified variants. Link to new certified-data.md.

Update docs/concepts/index.md and docs/guides/backends/certified-variables.md
to reference certified-data.md.

All 4 staging files under .migration/learn-hub/.../chain-key-cryptography/
consumed and deleted.
@marc0olo marc0olo requested a review from a team as a code owner May 6, 2026 15:16
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Review notes

This PR is clean. No broken links, no banned patterns, frontmatter complete (including sidebar.order), <!-- Upstream: --> comment present, and the certified-variables.md intro link update is correct.

One optional improvement (not blocking): network-overview.md has two existing references to certified-variables.md (the how-to guide) that could optionally be updated to also link to the new certified-data.md concept page for richer conceptual context. Up to editorial judgement.

Ready to merge.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Two issues to address before merging:

1. Em-dashes in docs/concepts/certified-data.md

Em-dashes are banned in prose per CLAUDE.md. Four instances in the body text need to be replaced:

  • Line 8: committed through consensus — without the client needing to replay any blockchain history → replace the em-dash with a comma
  • Line 14: against a **single, stable public key** — the Internet Computer's root public key → replace with parentheses or a colon
  • Line 18: the subnet computes a **certified state tree** — a hash tree representing → replace with a colon
  • Line 38: and cryptographic authentication — a combination not natively available → replace with a comma

2. Sidebar order collision in docs/concepts/certified-data.md

certified-data.md declares sidebar.order: 11, but vetkeys.md already uses order: 11. Suggested resolution:

File Current order Proposed order
certified-data.md 11 10
chain-fusion (current) 11
vetkeys.md 11 12
security (current) 13
governance (current) 14

Please verify the full ordering in the concepts sidebar before adjusting, as the right numbers depend on what other pages occupy orders 10 and above.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Content accuracy follow-up — chain-key-cryptography.md

The new subsection on key resharing states:

"runs periodically within a subnet to defend against adaptive attackers: each resharing invalidates all previously obtained shares, so compromising nodes over time does not help an adversary accumulate enough shares to forge signatures."

The Learn Hub source material only describes resharing occurring when subnet membership changes (e.g., node rotation). It does not describe periodic intra-subnet resharing as an adaptive adversary defense mechanism.

This claim may be accurate — it is consistent with how proactive secret sharing works in threshold cryptography — but it goes beyond what the migration source supports. Please verify it against the IC interface spec or dfinity/ic documentation before merging.

If not verifiable from available sources, the sentence should be narrowed to what is confirmed:

"resharing runs when subnet membership changes (e.g., during node rotation), ensuring that shares held by removed nodes become invalid."

- Replace 4 em-dashes in certified-data.md with commas, colon, or parentheses
- Resolve sidebar order collision: vetkeys 11->12, security 12->13
  (certified-data stays at 11 in the sequence after chain-fusion at 10)
- Narrow the resharing claim in chain-key-cryptography.md to what is
  confirmed from source material: resharing runs on membership changes,
  not described as periodic proactive secret sharing
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Feedback addressed:

  • Replaced 4 em-dashes in certified-data.md (lines 8, 14, 18, 38) with commas, colon, or parentheses
  • Resolved sidebar order collision: vetkeys.md bumped from 11 to 12, security.md bumped from 12 to 13; certified-data.md stays at 11 (between chain-fusion at 10 and vetkeys at 12)
  • Narrowed the resharing claim in chain-key-cryptography.md: removed the unverified statement about periodic intra-subnet resharing as an adaptive adversary defense; kept only what's confirmed (resharing runs when subnet membership changes, old shares become useless)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant