From cd3fc57ab41f066e50dbd0f864fbc91394c96f3d Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Tue, 28 Apr 2026 12:13:40 +0200 Subject: [PATCH] fix(jargon): rename onchain randomness to verifiable randomness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Renames the concept page (onchain-randomness.md → verifiable-randomness.md), updates both page titles, the guide section heading, and all cross-references in chain-key-cryptography.md, concepts/index.md, and languages/rust/index.md. Note: docs/languages/motoko/icp-features/randomness.md still uses the old term — it is auto-synced from caffeinelabs/motoko and must be fixed upstream. --- docs/concepts/chain-key-cryptography.md | 4 ++-- docs/concepts/index.md | 2 +- .../{onchain-randomness.md => verifiable-randomness.md} | 4 ++-- docs/guides/backends/randomness.md | 8 ++++---- docs/languages/rust/index.md | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) rename docs/concepts/{onchain-randomness.md => verifiable-randomness.md} (97%) diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index a41fceed..b1a83482 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/docs/concepts/chain-key-cryptography.md @@ -15,7 +15,7 @@ This design has several consequences for developers: - **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. - **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 variables](../guides/backends/certified-variables.md). -- **Onchain 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 [Onchain randomness](onchain-randomness.md). +- **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). - **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). ## Core protocols @@ -33,7 +33,7 @@ BLS is the signature scheme used for ICP's internal operations: consensus, respo BLS was chosen for two properties: 1. **Non-interactive signing.** A node holding a key share can independently produce a signature share. Shares are combined into a full signature with no further communication between nodes. -2. **Unique signatures.** For a given public key and message, exactly one valid BLS signature exists. This uniqueness is what makes onchain randomness unbiasable. No coalition of nodes can influence the output. +2. **Unique signatures.** For a given public key and message, exactly one valid BLS signature exists. This uniqueness is what makes the verifiable randomness unbiasable. No coalition of nodes can influence the output. ### Chain-key signatures (threshold ECDSA and Schnorr) diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 52872bed..0ae4745b 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -18,7 +18,7 @@ Understand the ideas behind the Internet Computer before you build on it. These - **[Cycles](cycles.md)**: How canisters pay for their own compute, storage, and bandwidth, and why users pay nothing. - **[Orthogonal Persistence](orthogonal-persistence.md)**: How canister memory survives across executions and upgrades without databases. - **[HTTPS Outcalls](https-outcalls.md)**: How canisters make HTTP requests to external services with consensus on responses. -- **[Onchain Randomness](onchain-randomness.md)**: Cryptographically secure random numbers using threshold VRF. +- **[Verifiable Randomness](verifiable-randomness.md)**: Cryptographically secure random numbers using threshold VRF. - **[Timers](timers.md)**: Periodic and one-shot scheduled tasks via the global timer mechanism. ## Cryptography and cross-chain diff --git a/docs/concepts/onchain-randomness.md b/docs/concepts/verifiable-randomness.md similarity index 97% rename from docs/concepts/onchain-randomness.md rename to docs/concepts/verifiable-randomness.md index d13609ff..0748bec0 100644 --- a/docs/concepts/onchain-randomness.md +++ b/docs/concepts/verifiable-randomness.md @@ -1,5 +1,5 @@ --- -title: "Onchain Randomness" +title: "Verifiable Randomness" description: "How ICP generates unpredictable random numbers using a threshold Verifiable Random Function, with no trusted party required" sidebar: order: 7 @@ -63,7 +63,7 @@ For applications that need verifiable randomness tied to a specific user or even ## Next steps -- [Onchain randomness guide](../guides/backends/randomness.md): how to call `raw_rand` and derive typed values in Motoko and Rust +- [Verifiable randomness guide](../guides/backends/randomness.md): how to call `raw_rand` and derive typed values in Motoko and Rust - [Management canister reference](../reference/management-canister.md#raw_rand): `raw_rand` API specification - [Chain-key cryptography](chain-key-cryptography.md): the cryptographic foundation underlying the threshold VRF - [Security](security.md): how randomness fits into the broader ICP security model diff --git a/docs/guides/backends/randomness.md b/docs/guides/backends/randomness.md index edbdebca..d629bf2e 100644 --- a/docs/guides/backends/randomness.md +++ b/docs/guides/backends/randomness.md @@ -1,5 +1,5 @@ --- -title: "Onchain Randomness" +title: "Verifiable Randomness" description: "Generate cryptographically secure random numbers in canisters using the management canister's raw_rand API" sidebar: order: 4 @@ -7,9 +7,9 @@ sidebar: [Canisters](../../concepts/canisters.md) can generate cryptographically secure random numbers directly from canister code. This guide shows how to call the `raw_rand` method, derive typed values from the returned bytes, and use randomness safely. -For how ICP produces unpredictable randomness without any trusted party, see [Onchain Randomness](../../concepts/onchain-randomness.md). +For how ICP produces unpredictable randomness without any trusted party, see [Verifiable Randomness](../../concepts/verifiable-randomness.md). -## Why onchain randomness is different +## Why verifiable randomness matters Consensus-based systems execute every transaction deterministically: every node replays the same operations and must reach the same state. This means you cannot use typical randomness sources like `Math.random()` or `/dev/urandom`: they would produce different values on each replica, breaking consensus. @@ -223,7 +223,7 @@ Note: this example predates `mo:core` and uses the older `Random.Finite` API. Th ## Next steps -- [Onchain Randomness (concept)](../../concepts/onchain-randomness.md): how the IC's threshold VRF works +- [Verifiable Randomness (concept)](../../concepts/verifiable-randomness.md): how the IC's threshold VRF works - [Management Canister](../../reference/management-canister.md): `raw_rand` API reference - [Data Integrity](../security/data-integrity.md): using randomness in a secure application design - [Inter-canister calls](../canister-calls/inter-canister-calls.md): async patterns and reentrancy diff --git a/docs/languages/rust/index.md b/docs/languages/rust/index.md index 66f716b0..3447f36a 100644 --- a/docs/languages/rust/index.md +++ b/docs/languages/rust/index.md @@ -203,7 +203,7 @@ Rust canisters compile to `wasm32-unknown-unknown`. Most pure-computation crates | Sleep / delays | `std::thread::sleep` | Use `ic-cdk-timers` to schedule future execution. | | Current time | `std::time::Instant` | `ic_cdk::api::time()` returns nanoseconds since the epoch. | | Environment variables | `std::env::var` | Not available at runtime. Use `env!()` or `option_env!()` to embed values at compile time. | -| Random numbers | `rand`, `getrandom` | Use `ic_cdk::management_canister::raw_rand()` for onchain randomness, or implement `getrandom::register_custom_getrandom!` for crates that depend on `getrandom`. | +| Random numbers | `rand`, `getrandom` | Use `ic_cdk::management_canister::raw_rand()` for verifiable randomness, or implement `getrandom::register_custom_getrandom!` for crates that depend on `getrandom`. | | Network I/O | `reqwest`, `hyper` | Use [HTTPS outcalls](../../guides/canister-calls/calling-from-clients.md) via the management canister. | Most crates that target `wasm32-unknown-unknown` for browser use (via `wasm-bindgen` or `wasm-pack`) will **not** work because they depend on JavaScript host bindings that do not exist in the ICP runtime.