docs: add protocol randomness, tribunals, and error reference pages#436
docs: add protocol randomness, tribunals, and error reference pages#436MuncleUscles wants to merge 1 commit into
Conversation
Add three protocol/reference docs pages sourced from genlayer-consensus v0.6-dev: - Protocol Randomness (concept): how the seed-chained, ECDSA-signature + keccak256 randomness mechanism drives stake-weighted validator/leader selection, per-recipient seed rotation, replay-resistance, and the acknowledged grinding / initial-seed limitations. - Deterministic Violations & Tribunals (concept): hash-mismatch detection of provably-wrong deterministic results, the liveness (idleness) vs safety (violation) split, the automatic tribunal adjudication, and the slashing (5% leader / 1% validator, 2-epoch delay) plus the ADR-025 designed permanent-ban outcome. - Error & Revert Reference (developer reference): the 280 custom errors from the consensus ABI, each with its keccak256 4-byte selector, a one-line meaning and cause/fix, grouped by area, plus common encoding pitfalls (RLP-wrapped write calldata). Wire all three into their _meta.json files and cross-link from the appeal-process, slashing, and staking-guide pages.
✅ Deploy Preview for genlayer-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Warning Review limit reached
Next review available in: 36 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
1 participant
Description
Adds three protocol/reference documentation pages, sourced from the
genlayer-consensusv0.6-devcontracts and spec, and wires them into navigation with cross-links.New pages
Protocol Randomness (concept) —
understand-genlayer-protocol/core-concepts/optimistic-democracy/protocol-randomnessExplains how validator and leader selection randomness works: a seed advanced by an ECDSA signature over the current seed and hashed with keccak256 (a seed chain), maintained per recipient; stake-weighted committee selection; per-round freshness; replay-resistance; and the acknowledged grinding and initial-seed limitations. Described strictly as signature-derived pseudo-randomness — not a verifiable random function — consistent with the implementation and GAP-012.
Deterministic Violations & Tribunals (concept) —
understand-genlayer-protocol/core-concepts/optimistic-democracy/deterministic-violations-and-tribunalsDefines a deterministic violation (a validator's result hash disagreeing with the committee majority), distinguishes it from idleness (liveness vs. safety, handled on separate paths), walks the automatic tribunal adjudication (commit-reveal by a broader validator set), and covers consequences: slashing (leader vs. validator rates, with a delay measured in epochs) that is implemented today, and the permanent-ban outcome that is the ADR-025 design target but is noted as not yet wired into the tribunal path on this branch.
Error & Revert Reference (developer reference) —
developers/error-referenceA catalog of 280 custom protocol errors, each with its 4-byte selector, a one-line meaning, and a common cause/fix, grouped by area (Fees, Staking, Consensus, Governance, Access, Other). Includes guidance on decoding a raw selector and common encoding pitfalls (e.g. write-transaction calldata must be
rlp.encode([calldata, leader_only]); sending raw calldata surfaces asRLP string ends with superfluous bytes).How the error table was generated
Error signatures were read from the consensus repo's canonical
scripts/utils/errorSelectors.ts(v0.6-dev). Each 4-byte selector was computed as the first four bytes ofkeccak256(type-only-signature)— the same method the repo's own generator uses. The set was validated against the known anchorFeeValueMustBeNonZero(uint256)=0x632be5a1, checked for selector collisions (none), and the 11 argument-bearing signatures were independently cross-checked to confirm they were hashed from type-only signatures (not parameter-named ones).Navigation & cross-links
protocol-randomnessanddeterministic-violations-and-tribunalsto the Optimistic Democracy_meta.json.error-referenceto the Developers_meta.json.appeal-processandslashing, and linked the error reference fromstaking-guide.Validation
node scripts/list-docs-routes.js— all three new routes resolve; full run clean (155 routes).node scripts/generate-full-docs.js— runs clean (210 pages); the new pages and the0x632be5a1anchor appear in the generated bundle.Content sourced from the contracts/spec; where the implementation and spec diverge (tribunal majority denominator, permanent-ban wiring, configurable strike threshold), the pages describe the behavior qualitatively and flag the design-vs-code gap rather than asserting unverified specifics.