docs: governance concepts

[marc0olo]

Summary

• NNS overview: purpose, canister roles, ICP token (governance, cycles, rewards), ledger
• Neurons: stake, dissolve delay, age, voting power formula, liquid democracy/following, known neurons
• Proposals: lifecycle (open → adopted/rejected → executed), types, wait-for-quiet extension, developer-relevant NNS proposals
• Voting rewards: maturity mechanism, declining reward rate schedule
• SNS: per-dApp governance canisters, token economics (developer/treasury/swap allocations), decentralization swap mechanics, SNS vs NNS comparison table
• Developer implications of decentralization (upgrade authorization, emergency proposals)
• Concepts-only page (no CLI procedures) — links to guides/governance/launching.md for how-to content

Sync recommendation

informed by dfinity/portal — docs/building-apps/governing-apps/tokenomics/; informed by dfinity/icskills — sns-launch

[marc0olo]

Review: Governance

Must fix

• Voting power formula values unverified for NNS: The page states "up to 2x at 8 years" and "up to 1.25x at 4 years" for NNS neuron voting power bonuses. The sns-launch skill confirms these as SNS example parameters (100% dissolve delay bonus, 25% age bonus), but the portal source material does not explicitly document these numbers for the NNS. These values are widely cited and likely correct, but the page should add <!-- Needs human verification: NNS neuron voting power bonus percentages (2x at 8 years, 1.25x at 4 years) — not explicitly stated in portal source material --> until they can be confirmed against the NNS governance canister specification.

• Reward rate decline claim is vague and unverified: "The reward rate declines over time as the protocol matures, converging toward a lower floor rate over roughly a decade." This claim is not documented in the portal source material reviewed. The portal tokenomics files do not cover the NNS reward rate schedule. Either cite a source or add a <!-- Needs human verification: NNS reward rate convergence timeline --> flag.

Suggestions

• Known neuron minimum stake wording is imprecise: The page says "Any neuron with at least 25 ICP staked can submit a RegisterKnownNeuron proposal." The portal source (becoming-a-known-neuron.mdx) says "The proposal can be submitted by any neuron that has at least 25 ICP staked." This is technically correct. However, the 10 ICP + 6 months dissolve delay threshold (required for any proposal submission) is a prerequisite that applies here too. The current wording implies 25 ICP is the only gating factor. Suggest clarifying: "Any neuron with at least 10 ICP staked and 6 months dissolve delay can submit NNS proposals, including RegisterKnownNeuron which additionally requires at least 25 ICP staked."

• Maturity randomness note is slightly imprecise: "Neurons can convert maturity to ICP (with some randomness that approximates the expected value)". The portal describes this as "maturity modulation" — a ±5% variation in how much ICP is minted. The current parenthetical ("with some randomness that approximates the expected value") is confusing because "approximates the expected value" implies randomness averages out to a target, but maturity modulation is specifically a 7-day rolling average mechanism to prevent gaming. Suggest: "with a modulation of ±5% applied to the mint amount".

• NNS proposal types list is incomplete but adequate: The page lists only four proposal types that affect developers. This is a concepts page so exhaustive coverage is not expected, but adding a note like "See system canisters reference for the full list of NNS proposal topics and types" would help developers who need more depth.

• "Roughly a decade" for reward rate — point to authoritative source: If this claim remains, link to the Learn Hub article on tokenomics (https://learn.internetcomputer.org/hc/en-us/articles/34090810571284) which is listed in the stub's source material. The reward rate convergence timeline is covered there. This would satisfy the source requirement and avoid the unverified claim issue.

• Content brief coverage gap — tokenomics basics: The content brief specifies "tokenomics basics (ICP token, voting rewards)" and the page covers both, but it does not address the ICP-to-cycles conversion relationship in enough depth for developers. The page says "converted into cycles, which power canister computation and storage" and "the NNS sets the ICP-to-cycles conversion rate" but this is the main reason developers care about ICP economics. This could be enhanced with one sentence explaining the denominator (SDR peg) for developers who wonder why cycle costs remain stable. The page does mention "anchored to the IMF SDR" — this is present, just very brief.

Verified

• All internal links resolve: ../guides/governance/launching.md, ../guides/governance/managing.md, and ../reference/system-canisters.md all confirmed present on disk.
• No banned patterns: No dfx references, no mo:base imports, no internetcomputer.org/docs/ links. No CLI commands (appropriate for a concepts page).
• Frontmatter complete: title, description, and sidebar.order all present and consistent with page body.
• Upstream comment present: <!-- Upstream: informed by dfinity/portal — ... --> correctly lists all portal files and icskill used.
• File type correct: .md (no interactive components needed — correct choice per project conventions).
• Canister IDs verified: NNS governance rrkah-fqaaa-aaaaa-aaaaq-cai and SNS-W qaa6y-5yaaa-aaaaa-aaafa-cai confirmed against portal and sns-launch skill.
• Proposal lifecycle: "4 days, extending up to 8 days" confirmed in portal (proposal-submit.mdx: "open to voting for 4 days … deadline will be automatically extended up to an additional 4 days").
• Neuron proposal threshold: "Minimum stake to submit proposals is 10 ICP with at least 6 months of dissolve delay" confirmed against portal (proposal-submit.mdx).
• Known neuron threshold: "25 ICP staked" confirmed in portal (becoming-a-known-neuron.mdx).
• SNS canister count and names: Six canisters (Governance, Ledger, Root, Swap, Index, Archive) confirmed against sns-launch skill.
• SNS subnet: Confirmed in portal (launch-summary-1proposal.mdx).
• Content brief coverage: NNS governance, SNS framework, neurons, proposals lifecycle, tokenomics basics, and developer implications for SNS — all addressed per the brief.
• Diataxis compliance: Concepts page with no CLI commands, no step-by-step procedures, appropriate "what/why" explanations throughout.
• Next steps section: Present with three targeted links.
• Reader test: Opening paragraph delivers on the title immediately, explains both governance systems and why developers care. No assumed context.
• Scanability: Good heading structure — each major section has a clear heading. Key terms are bolded within sections. The NNS proposal types sub-list uses italics for proposal type names, making them scannable.
• No verification TODO flags present.

[marc0olo]

<!-- feedback-addressed -->

Feedback addressed for PR #68 — docs/concepts/governance.md

Changes applied

Must-fix items:

• Voting power bonus percentages (2x at 8 years, 1.25x at 4 years): Added <\!-- Needs human verification --> comment flagging that these values match SNS default parameters in the sns-launch skill but are not explicitly stated in the portal NNS source material. The values remain in the page body as they are widely accepted; the comment directs a human reviewer to confirm against the NNS governance canister specification.

• Reward rate convergence claim: Added a link to the ICP tokenomics overview on Learn Hub at the end of the reward rate sentence. This sources the "roughly a decade" claim and satisfies the verification requirement without removing the useful developer context.

Suggestions applied:

• Known neuron prerequisite clarification: Rewrote the sentence to make the prerequisite chain explicit: "Any neuron that meets the general proposal prerequisite (at least 10 ICP staked with 6 months dissolve delay) and has at least 25 ICP staked can submit a RegisterKnownNeuron proposal." Verified both thresholds against portal source (proposal-requirements.mdx confirms 10 ICP + 6 months; becoming-a-known-neuron.mdx confirms 25 ICP for RegisterKnownNeuron).

• Maturity modulation language: Changed "with some randomness that approximates the expected value" to "with a modulation of ±5% applied to the mint amount". The portal staking.mdx references "maturity modulation" and the Rosetta construction API mentions "worst-case maturity modulation" confirming the mechanism exists; the ±5% figure is consistent with documented NNS behavior.

• System canisters reference for full proposal list: Added "See system canisters for the full list of NNS proposal topics and types." immediately after the developer-facing proposals list.

Items skipped

• SDR peg depth (content brief coverage gap suggestion): The reviewer noted the ICP-to-cycles/SDR anchor is "just very brief" and could be enhanced. Not applied because: (a) rated as low-severity, (b) the page already correctly states "anchored to the IMF SDR", and (c) adding technical depth about the conversion mechanism would push this concepts page toward reference territory.

Build note

The npm run build command failed due to a pre-existing issue in docs/guides/backends/https-outcalls.mdx (missing .sources/examples snippet file — the examples submodule was not initialized due to SSH access restrictions in this worktree). This error is unrelated to the governance page changes and exists on the branch prior to this commit. No governance-related build errors were present.