Skip to content

Commit cd6cbbb

Browse files
committed
docs(cryptography): apply brand voice fixes to cryptography deep-dive pages
Remove "blockchain" comparisons from certified-data.md intro paragraphs. Replace "cross-chain" with "crosschain" and "other blockchains" with "other chains" in chain-key-cryptography.md. Replace "blockchain address" with "network address". Fix DAO reference in security.md. Remove em-dashes from Upstream comments. Fix "learn hub staging:" Upstream comment format.
1 parent b4f1eb0 commit cd6cbbb

4 files changed

Lines changed: 15 additions & 15 deletions

File tree

docs/concepts/certified-data.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ sidebar:
55
order: 11
66
---
77

8-
Query calls on ICP return results immediately without going through consensus. This means the response comes from a single replica, and a client cannot inherently distinguish a legitimate response from a fabricated one. Certified data solves this: by embedding cryptographic certificates in query responses, canisters can prove that their response reflects state that was committed through consensus, without the client needing to replay any blockchain history.
8+
Query calls on ICP return results immediately without going through consensus. This means the response comes from a single replica, and a client cannot inherently distinguish a legitimate response from a fabricated one. Certified data solves this: by embedding cryptographic certificates in query responses, canisters can prove that their response reflects state that was committed through consensus, without the client needing to replay any historical state.
99

1010
## The verification problem
1111

12-
On most blockchains, clients that want to verify data without trusting a single node must do significant work. Bitcoin's Simplified Payment Verification downloads and validates block headers. Ethereum's light clients maintain a chain of committee hashes and verify Merkle proofs against the state root. Both approaches require ongoing synchronization and are impractical for mobile or web applications that need fast, lightweight verification.
12+
Traditional verification approaches require significant client-side work. Bitcoin's Simplified Payment Verification downloads and validates block headers. Ethereum's light clients maintain a chain of committee hashes and verify Merkle proofs against the state root. Both approaches require ongoing synchronization and are impractical for mobile or web applications that need fast, lightweight verification.
1313

14-
ICP takes a different approach: instead of requiring clients to maintain any blockchain state, the protocol produces a certificate that can be verified with a single signature check against a **single, stable public key** (the Internet Computer's root public key). This key never changes (it was fixed at genesis and is published in the NNS governance system), so any client can embed it and immediately verify any certificate it receives.
14+
ICP takes a different approach: instead of requiring clients to track any chain state, the protocol produces a certificate that can be verified with a single signature check against a **single, stable public key** (the Internet Computer's root public key). This key never changes (it was fixed at genesis and is published in the NNS governance system), so any client can embed it and immediately verify any certificate it receives.
1515

1616
## How certificates are produced
1717

@@ -35,7 +35,7 @@ The interface through which canisters participate in this mechanism is **certifi
3535

3636
The 32-byte limitation is not a problem in practice. Applications use standard data structures like [Merkle trees](https://en.wikipedia.org/wiki/Merkle_tree) to commit to arbitrarily large amounts of data in a single 32-byte root hash. The canister stores the full data structure locally and returns a Merkle witness (a path from the root to the requested value) alongside the certificate in each query response. The client verifies both the certificate signature and the witness together.
3737

38-
This pattern allows canisters to provide both fast responses (query, no consensus delay) and cryptographic authentication, a combination not natively available in most blockchain systems.
38+
This pattern allows canisters to provide both fast responses (query, no consensus delay) and cryptographic authentication, a combination that most distributed systems cannot offer without full state replay.
3939

4040
## Applications
4141

docs/concepts/chain-key-cryptography.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
---
22
title: "Chain-Key Cryptography"
3-
description: "Threshold signatures that enable cross-chain integration, fast verification, and chain evolution"
3+
description: "Threshold signatures that enable crosschain integration, fast verification, and chain evolution"
44
sidebar:
55
order: 9
66
---
77

8-
Chain-key cryptography is a set of threshold cryptographic protocols that underpin the Internet Computer. Instead of any single node holding a private key, keys are split into shares distributed across the nodes of a [subnet](network-overview.md). Nodes collaboratively sign messages without ever reconstructing the full key: and this single capability enables everything from fast response verification to canisters signing transactions on Bitcoin, Ethereum, and dozens of other blockchains.
8+
Chain-key cryptography is a set of threshold cryptographic protocols that underpin the Internet Computer. Instead of any single node holding a private key, keys are split into shares distributed across the nodes of a [subnet](network-overview.md). Nodes collaboratively sign messages without ever reconstructing the full key: and this single capability enables everything from fast response verification to canisters signing transactions on Bitcoin, Ethereum, and dozens of other chains.
99

1010
## Why threshold cryptography matters
1111

12-
On most blockchains, verifying state requires replaying transactions or trusting a full node. On ICP, verifying a response means checking **one signature against one public key**: regardless of how many nodes produced it. This is possible because each subnet holds a threshold BLS key: any sufficiently large subset of nodes can produce a valid signature, but no smaller group can forge one.
12+
On traditional distributed networks, verifying state requires replaying transactions or trusting a full node. On ICP, verifying a response means checking **one signature against one public key**: regardless of how many nodes produced it. This is possible because each subnet holds a threshold BLS key: any sufficiently large subset of nodes can produce a valid signature, but no smaller group can forge one.
1313

1414
This design has several consequences for developers:
1515

1616
- **Fast verification.** Clients verify subnet responses with a single public key check. There is no need to download block headers or maintain a light client.
1717
- **Certified data.** Canisters can set certified variables that the subnet signs at each block. Query responses that include these certificates are cryptographically authenticated, bridging the gap between fast queries and trusted updates. See [Certified data](certified-data.md) for the conceptual explanation and [Certified variables](../guides/backends/certified-variables.md) for the implementation guide.
1818
- **Verifiable randomness.** The threshold BLS scheme produces unique signatures: for a given message and key, only one valid signature exists. ICP exploits this property to generate unpredictable, unbiased random numbers that canisters can consume. See [Verifiable randomness](verifiable-randomness.md).
19-
- **Cross-chain signing.** Canisters can request threshold ECDSA and Schnorr signatures, giving them the ability to control addresses and sign transactions on external blockchains. This is the foundation of [Chain Fusion](chain-fusion.md).
19+
- **Crosschain signing.** Canisters can request threshold ECDSA and Schnorr signatures, giving them the ability to control addresses and sign transactions on external chains. This is the foundation of [Chain Fusion](chain-fusion.md).
2020

2121
## Core protocols
2222

@@ -37,7 +37,7 @@ BLS was chosen for two properties:
3737

3838
### Chain-key signatures (threshold ECDSA and Schnorr)
3939

40-
Chain-key signatures extend threshold cryptography beyond ICP's internal operations. They let canisters hold keys for external signature schemes and sign arbitrary messages, which means canisters can control accounts on other blockchains.
40+
Chain-key signatures extend threshold cryptography beyond ICP's internal operations. They let canisters hold keys for external signature schemes and sign arbitrary messages, which means canisters can control accounts on other chains.
4141

4242
Two signature schemes are supported, with the Schnorr API offering two algorithm variants:
4343

@@ -70,9 +70,9 @@ For ECDSA and BIP340, key derivation uses a generalized form of [BIP-32](https:/
7070

7171
Derivation is transparent: it happens inside the protocol as part of the signing and public-key-retrieval APIs. You provide a derivation path and the protocol handles the rest.
7272

73-
Because the derivation algorithm is deterministic and uses only public parameters (the master public key, the canister principal, and the derivation path), public key derivation can also be performed **offline**: no management canister call or network connection required. This is useful for building explorers, dashboards, or address-derivation tools that need a canister's public key or blockchain address without a live ICP connection. See the [offline key derivation guide](../guides/chain-fusion/offline-key-derivation.md) for TypeScript and Rust libraries.
73+
Because the derivation algorithm is deterministic and uses only public parameters (the master public key, the canister principal, and the derivation path), public key derivation can also be performed **offline**: no management canister call or network connection required. This is useful for building explorers, dashboards, or address-derivation tools that need a canister's public key or network address without a live ICP connection. See the [offline key derivation guide](../guides/chain-fusion/offline-key-derivation.md) for TypeScript and Rust libraries.
7474

75-
<!-- ic-pub-key: known issue@dfinity/ic-pub-key v1.0.1 npm package is missing .d.ts type declarations (https://github.com/dfinity/ic-pub-key/issues/197); verify this is fixed before editing TypeScript examples. Package may also move to the @icp-sdk/ namespace in a future release update all references when that happens. -->
75+
<!-- ic-pub-key: known issue: @dfinity/ic-pub-key v1.0.1 npm package is missing .d.ts type declarations (https://github.com/dfinity/ic-pub-key/issues/197); verify this is fixed before editing TypeScript examples. Package may also move to the @icp-sdk/ namespace in a future release; update all references when that happens. -->
7676

7777
### Pre-signatures
7878

@@ -99,7 +99,7 @@ For signing costs, see [Cycles costs](../references/cycles-costs.md).
9999

100100
## Supported chains
101101

102-
Any blockchain whose transaction authentication uses ECDSA (secp256k1) or Schnorr signatures (BIP340 over secp256k1, or Ed25519) can be integrated with ICP through chain-key signatures. For the full list of supported chains with integration methods and chain-key tokens, see [Chain Fusion: Supported chains](chain-fusion.md#supported-chains).
102+
Any chain whose transaction authentication uses ECDSA (secp256k1) or Schnorr signatures (BIP340 over secp256k1, or Ed25519) can be integrated with ICP through chain-key signatures. For the full list of supported chains with integration methods and chain-key digital assets, see [Chain Fusion: Supported chains](chain-fusion.md#supported-chains).
103103

104104
## Chain evolution
105105

@@ -117,4 +117,4 @@ For more on how upgrades work at the protocol level, see the [Chain Evolution](h
117117
- [VetKeys](vetkeys.md): a related cryptographic primitive for onchain encryption
118118
- [Management canister reference](../references/management-canister.md): the threshold signing API
119119

120-
<!-- Upstream: informed by dfinity/portal docs/references/t-sigs-how-it-works.mdx, docs/building-apps/chain-fusion/overview.mdx, docs/building-apps/chain-fusion/supported-chains.mdx; learn hub staging: chain-key-cryptography/chain-key-cryptography.md, chain-key-cryptography/subnet-keys-and-subnet-signatures.md, chain-key-cryptography/chain-key-signatures.md -->
120+
<!-- Upstream: informed by dfinity/portal (docs/references/t-sigs-how-it-works.mdx, docs/building-apps/chain-fusion/overview.mdx, docs/building-apps/chain-fusion/supported-chains.mdx); informed by Learn Hub articles "Chain-Key Cryptography", "Subnet Keys and Subnet Signatures", "Chain-Key Signatures" (migrated, source retired) -->

docs/concepts/security.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ See [Upgrade safety](../guides/security/canister-upgrades.md) for patterns that
8787

8888
### Controller risk
8989

90-
Canister controllers can change the code, extract funds, or delete the canister at any time. If a single person or team controls a canister that holds user assets, users must trust that entity completely. For applications where this trust is unacceptable, control can be transferred to a DAO (such as an [SNS](../guides/governance/launching.md)) or the canister can be made immutable by removing all controllers.
90+
Canister controllers can change the code, extract funds, or delete the canister at any time. If a single person or team controls a canister that holds user assets, users must trust that entity completely. For applications where this trust is unacceptable, control can be transferred to an [SNS](../guides/governance/launching.md) or the canister can be made immutable by removing all controllers.
9191

9292
Users can verify a canister's controllers through the IC dashboard or by querying the canister's information via a `read_state` request.
9393

docs/guides/backends/certified-variables.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -364,4 +364,4 @@ See [Frontend certification](../../guides/frontends/certification.md) for the as
364364
- [IC Interface Specification: Certified Data](../../references/ic-interface-spec/canister-interface.md#system-api-certified-data): the certified data system API
365365
- [IC Interface Specification: Certification](../../references/ic-interface-spec/certification.md): certificate format and delegation
366366

367-
<!-- Upstream: informed by dfinity/portal docs/building-apps/security/data-integrity-and-authenticity.mdx; dfinity/icskills skills/certified-variables/SKILL.md; dfinity/cdk-rs library/ic-certified-map/src/lib.rs, ic-cdk/src/api.rs; caffeinelabs/motoko-core src/CertifiedData.mo; dfinity/examples motoko/cert-var; dfinity/response-verification README.md -->
367+
<!-- Upstream: informed by dfinity/portal (docs/building-apps/security/data-integrity-and-authenticity.mdx); dfinity/icskills (skills/certified-variables/SKILL.md); dfinity/cdk-rs (library/ic-certified-map/src/lib.rs, ic-cdk/src/api.rs); caffeinelabs/motoko-core (src/CertifiedData.mo); dfinity/examples (motoko/cert-var); dfinity/response-verification (README.md) -->

0 commit comments

Comments
 (0)