docs: on-chain randomness concept page

[marc0olo]

Summary

• Explains why deterministic execution makes blockchain randomness hard and why naive approaches (block hashes, commit-reveal, trusted oracles) fail
• Covers ICP's threshold VRF: how replicas collaborate each round using chain-key cryptography to produce a verifiable, unbiasable 32-byte random tape
• Explains security properties (unpredictability, unbiasability, verifiability), the one-round delay, and the update-only constraint of raw_rand
• Applications section: fair selection, games, cryptographic protocols; when to layer a commit-reveal scheme; pointer to vetKeys for per-user VRF

Sync recommendation

informed by dfinity/portal — randomness.mdx, vetkeys/verifiable-random-function.mdx; dfinity/cdk-rs — management_canister.rs; caffeinelabs/motoko-core — Random.mo

[marc0olo]

Review: Onchain Randomness

Must fix

• Inconsistent terminology: "vetKD" vs "VetKeys": Line 62 reads "see the vetKD VRF functionality described in vetKeys." All other pages in this project (security.md, chain-key-cryptography.md, index.md) use "VetKeys" as the feature name. The portal source (vetkeys/introduction.mdx) clarifies: "VetKeys" is the user-facing feature; "vetKD" is the underlying protocol name. Change to "see the vetKeys VRF functionality described in vetKeys" for consistency.

• Unsupported "fallback" claim in Unbiasability section: The page states "A malicious node that refuses to contribute forces a fallback, but cannot steer the result toward a preferred value." The portal source material does not describe a "fallback" mechanism. In ICP's threshold scheme, a threshold (not all) nodes must participate — if fewer than the threshold cooperate, the round itself stalls; it does not fall back to an alternative. "Forces a fallback" implies a graceful degradation path that the source material does not support. Suggested fix: "A malicious node cannot single-handedly prevent the subnet from producing randomness — a threshold of honest nodes is sufficient — but it cannot steer the result toward a preferred value."

Suggestions

• Step 3 phrasing ("in that round") vs portal source ("previous round"): Step 3 says "The random tape is then used to produce individual random values for each canister that requested randomness in that round." The portal source says the tape is used for canisters that requested randomness "in the previous round." Both describe the same relationship from different temporal frames, but the portal phrasing is more precise. The "One round of delay" section below correctly states that a call submitted in round N receives entropy from round N+1, which implies round N+1's tape serves round-N requests. Consider aligning Step 3 with the portal: "The random tape is then used to produce individual random values for each canister that requested randomness in the previous round."

• Step 4 "processes the call" is ambiguous: Step 4 says "The raw_rand result is determined during the round in which the management canister processes the call." Developers may be uncertain whether "processes" means submission or resolution. The "One round of delay" bullet directly below clarifies this correctly; consider adding a cross-reference in Step 4 or rewording to: "The raw_rand result is determined in the round after the call arrives (see one-round delay below)."

Verified

• All internal links resolve: chain-key-cryptography.md, vetkeys.md, security.md, ../guides/backends/randomness.md, ../reference/management-canister.md all exist as files on disk.
• The management-canister.md#raw_rand anchor exists (confirmed at line 320 of the reference page).
• No banned patterns: no dfx, no mo:base, no internetcomputer.org/docs/ or docs.internetcomputer.org URLs, no .mdx imports or JSX.
• No external URLs in body text.
• No CLI commands in a concepts page (correct per Diataxis rules for concepts/ — explanation only).
• No inline code snippets to verify.
• Frontmatter complete: title, description, and sidebar order all present.
• <\!-- Upstream: --> comment present and correctly formatted at end of file.
• "onchain" spelled without hyphen per content-authoring.md spelling rules.
• ## Next steps section uses correct heading variant.
• Build passes cleanly (npm run build: 86 pages, 0 errors, 0 warnings on this page).
• Content brief coverage complete: all four required topics addressed (why randomness is hard on blockchains, the VRF approach, security guarantees, developer-facing constraints including update-calls-only).
• 32-byte return value verified against IC interface spec (line 2745).
• "Update calls only" constraint confirmed against portal source randomness.mdx.
• "One round of delay" confirmed against portal source and management-canister reference.
• Source material consulted: .sources/portal/docs/building-apps/network-features/randomness.mdx and .sources/portal/docs/building-apps/network-features/vetkeys/verifiable-random-function.mdx.

[marc0olo]

<!-- feedback-addressed -->
Feedback addressed for PR #74 (docs/concepts/onchain-randomness.md):

Changes applied

Must fix

1. Terminology: "vetKD" → "vetKeys" (line 62)

   • Before: see the vetKD VRF functionality described in [vetKeys](vetkeys.md)
   • After: see the vetKeys VRF functionality described in [vetKeys](vetkeys.md)
   • Rationale: Portal introduction.mdx confirms "vetKeys" is the user-facing feature name; "vetKD" is the underlying protocol. All other pages in the project use "vetKeys" for the feature.

2. Unbiasability: replaced unsupported "fallback" claim

   • Before: A malicious node that refuses to contribute forces a fallback, but cannot steer the result toward a preferred value.
   • After: A malicious node cannot single-handedly prevent the subnet from producing randomness — a threshold of honest nodes is sufficient — but it cannot steer the result toward a preferred value.
   • Rationale: Portal source material does not describe a "fallback" mechanism. In ICP's threshold scheme a threshold (not all) nodes must participate; "fallback" implies a graceful degradation path that does not exist at this level.

Suggestions applied

3. Step 3: "in that round" → "in the previous round"

   • Before: The random tape is then used to produce individual random values for each canister that requested randomness in that round.
   • After: The random tape is then used to produce individual random values for each canister that requested randomness in the previous round.
   • Rationale: Portal randomness.mdx explicitly says "in the previous round". Aligns with the "one round of delay" section below.

4. Step 4: clarified delivery timing with cross-reference

   • Before: The raw_rand result is determined during the round in which the management canister processes the call, not when the canister submits it.
   • After: The raw_rand result is determined in the round after the call arrives (see one-round delay below), not when the canister submits it.
   • Rationale: "processes the call" was ambiguous about submission vs. resolution timing. Adding a forward reference to the "one-round delay" bullet removes the ambiguity.

Items skipped

None — all four feedback items were factually supported by portal source material and improve accuracy or clarity.

Build note

The build fails in this worktree due to the examples submodule not being initialized (SSH key access is blocked in the sandbox). The failure is in an unrelated file (docs/guides/backends/https-outcalls.mdx) and is pre-existing — confirmed by verifying the same error occurs on the original branch before any changes. The reviewer's environment confirmed the build passes cleanly (86 pages, 0 errors) for this page.