docs: managing an SNS guide

[marc0olo]

Summary

• How SNS proposals work: voting rules, wait-for-quiet, blocked types during swap
• All native proposal types with verified CLI syntax (motion, upgrades, metadata, treasury transfers, etc.)
• Custom proposals via generic nervous system functions with security considerations
• Cycles management: finding all SNS canisters, topping up
• Asset canister update workflow via proposals (5-step process)
• Neuron management and common operational mistakes

Sync recommendation

informed by dfinity/portal — docs/building-apps/governing-apps/managing/*; dfinity/icskills — sns-launch; dfinity/examples — stake_neuron_from_cli; dfinity/icp-cli — cli.md

[marc0olo]

Review: Managing an SNS

Must fix

• icp deploy --by-proposal and icp deploy --compute-evidence are not valid icp-cli flags: The Asset canister updates section (Steps 2 and 3) uses icp deploy FRONTEND_CANISTER_NAME --by-proposal -e ic and icp deploy FRONTEND_CANISTER_NAME --compute-evidence -e ic. These flags do not exist in icp-cli — they come from dfx deploy. The portal source (sns-asset-canister.mdx) explicitly uses dfx deploy FRONTEND_CANISTER_NAME --network ic --by-proposal. Since the project bans dfx, the correct approach is to document the underlying API calls directly: staging assets via the asset canister's batch APIs (create_batch, create_chunk, create_asset, set_asset_content, propose_commit_batch) or link to an external tool that supports SNS asset updates with icp-cli. Verified against .sources/icp-cli/docs/reference/cli.md — icp deploy has no --by-proposal or --compute-evidence flag.

• stake_neuron_from_cli example is NNS-specific, not SNS-specific: Line 602 refers the reader to dfinity/examples/rust/stake_neuron_from_cli for "the two-step SNS neuron staking process." Verified in .sources/examples/rust/stake_neuron_from_cli/src/lib.rs — this example hardcodes NNS_GOVERNANCE_CANISTER_ID = "rrkah-fqaaa-aaaaa-aaaaq-cai" (NNS governance) and calls claim_or_refresh_neuron_from_account on the NNS ledger. The SNS neuron staking flow uses the SNS ledger and SNS governance canisters. Pointing to an NNS example for SNS neuron creation will mislead developers. Either link to an SNS-specific example or remove the claim and replace it with a direct Learn Hub link.

• Broken internal link text: Line 10 uses [concepts/governance.md](../../concepts/governance.md) — the link text exposes a file path rather than a human-readable title. Should be something like [SNS governance concepts](../../concepts/governance.md).

• dfx path reference in example code: Line 35 sets PEM_FILE="/home/user/.config/dfx/identity/my-identity/identity.pem". The .config/dfx/identity/ path is dfx-specific; this is the only remaining dfx reference in the page. Since quill accepts any PEM file, the example should use a neutral path like /home/user/.config/quill/identity.pem or a generic placeholder like ~/.config/identity.pem.

Suggestions

• AddGenericNervousSystemFunction examples omit the topic field: The portal source (making-proposals.mdx, line 916) shows that GenericNervousSystemFunction now includes a topic : opt Topic field, and states "The proposer must also define what topic the new generic function should fall under." Both AddGenericNervousSystemFunction examples in the page (the general example on line 377 and the asset canister example on line 509) omit topic. Since the field is optional (opt Topic) the omission is technically valid, but guidance on choosing a topic would help readers who are seeing the current governance interface.

• Missing native proposal types documented in portal: The portal source lists RegisterExtension, ManageDappCanisterSettings, and UpgradeSnsToNextVersion as native SNS proposal types. UpgradeSnsToNextVersion is deprecated (portal recommends AdvanceSnsTargetVersion instead) so its omission is defensible. ManageDappCanisterSettings (for setting memory limits, compute allocation, log visibility on dapp canisters) is useful for operators and is absent. RegisterExtension is described as "under development" in portal, so omission is acceptable. Consider adding at least a brief mention of ManageDappCanisterSettings in a future iteration.

• AdvanceSnsTargetVersion example uses new_target = null: This is valid per the type (new_target : opt SnsVersion), but the explanation does not clarify what null means — it means "advance to the next approved version on SNS-W's upgrade path" (not a specific target). Adding one line of clarification would prevent confusion.

• from_treasury field encoding not explained: The TransferSnsTreasuryFunds section documents that from_treasury = 1 means ICP and from_treasury = 2 means SNS tokens (line 267), but neither the portal source nor the SNS governance Candid spec in .sources/ provides explicit documentation of these enum values. This appears correct based on portal examples, but the source of truth should be flagged: verify ICPS_TREASURY_TRANSFER = 1 and SNS_TOKEN_TREASURY_TRANSFER = 2 against the SNS governance proto or Candid spec before the page ships. This is a <!-- TODO: verify --> candidate.

• Cycles management section's get_sns_canisters_summary call arguments: The call uses '(record { update_canister_list = opt false })'. The portal source does not show this exact call; it only says to use get_sns_canisters_summary. The argument format should be verified against the SNS root canister's Candid interface before the page ships. Another <!-- TODO: verify --> candidate.

• Reader test — opening could be stronger: The first paragraph is good, but "the community does" is colloquial for technical documentation. Minor wording suggestion: "every upgrade, parameter change, treasury transfer, and asset update must go through an SNS proposal and be approved by token-holder vote" is clear and strong — consider opening with this rather than the "no single entity controls" framing.

Verified

• All internal links resolve: ../../concepts/governance.md → docs/concepts/governance.md ✓; launching.md → docs/guides/governance/launching.md ✓; testing.md → docs/guides/governance/testing.md ✓; ../../guides/canister-management/large-wasm.md → docs/guides/canister-management/large-wasm.md ✓; ../canister-management/cycles-management.md → docs/guides/canister-management/cycles-management.mdx (Astro resolves .md to .mdx) ✓
• icp canister top-up --amount 50t -e ic syntax verified against .sources/icp-cli/docs/reference/cli.md ✓
• icp cycles mint --icp 1 -e ic syntax verified against .sources/icp-cli/docs/reference/cli.md ✓
• icp canister call <CANISTER> <METHOD> <ARGS> -e ic syntax verified ✓
• icp canister status command exists in CLI reference ✓
• Treasury rate-limit table values match portal source (making-proposals.mdx lines 704–715) ✓
• SNS starting cycle counts (180T for SNS canisters, 60T for ledger) match portal cycles-usage.mdx ✓
• NervousSystemParameters Candid type matches portal source ✓
• TransferSnsTreasuryFunds, MintSnsTokens, ManageSnsMetadata, ManageLedgerParameters type signatures match portal source ✓
• RegisterDappCanisters and DeregisterDappCanisters type signatures match portal source ✓
• AddGenericNervousSystemFunction, ExecuteGenericNervousSystemFunction, RemoveGenericNervousSystemFunction structure matches portal source ✓
• Archive canister caution matches portal cycles-usage.mdx ✓
• stake_neuron_from_cli example exists in .sources/examples/rust/stake_neuron_from_cli/ ✓ (but see accuracy issue above)
• Frontmatter is complete and correct (title, description, sidebar order) ✓
• No dfx commands (only a dfx path string — see must-fix above) ✓
• No mo:base imports ✓
• No .mdx created (correct, this page doesn't need tabs) ✓
• <!-- Upstream: --> comment present at end of file ✓
• Learn Hub links use learn.internetcomputer.org domain ✓
• No links to internetcomputer.org/docs/ or docs.internetcomputer.org ✓
• Content brief coverage: the page covers all major areas listed in the source material (proposals, cycles, asset updates, neuron management) ✓
• Funnel structure (orient → instruct → next steps) followed ✓
• Code snippet inline length: all examples are under 30 lines or are reference-level Candid type definitions ✓

[marc0olo]

Feedback addressed: Managing an SNS (PR #101)

Changes applied

Must-fix items:

1. icp deploy --by-proposal and --compute-evidence removed — These flags do not exist in icp-cli (verified against .sources/icp-cli/docs/reference/cli.md). Steps 2 and 3 of the asset canister update workflow have been rewritten to document the underlying asset canister batch APIs directly: create_batch, create_chunk, create_asset, set_asset_content, and propose_commit_batch, all called via icp canister call. The evidence verification step now documents manual re-computation and the validate_commit_proposed_batch method as alternatives to the removed dfx-specific flag.

2. stake_neuron_from_cli reference replaced — The linked example (dfinity/examples/rust/stake_neuron_from_cli) hardcodes NNS_GOVERNANCE_CANISTER_ID = "rrkah-fqaaa-aaaaa-aaaaq-cai" and targets NNS governance (verified in .sources/examples/rust/stake_neuron_from_cli/src/lib.rs). Replaced the link with an inline explanation of the SNS two-step staking flow and a clear note that it is distinct from NNS neuron staking. The existing Learn Hub links for SNS Neurons and SNS Rewards are retained.

3. Broken internal link text fixed — [concepts/governance.md](...) changed to [SNS governance concepts](...).

4. dfx path reference neutralized — PEM_FILE="/home/user/.config/dfx/identity/my-identity/identity.pem" changed to PEM_FILE="/home/user/.config/quill/identity.pem". This removes the only remaining dfx reference from the page.

Suggestions applied:

5. AdvanceSnsTargetVersion null clarified — Added inline comment explaining that new_target = null means "advance to the next approved version on SNS-W's upgrade path."

6. from_treasury field flagged for verification — Added <!-- Needs human verification --> comment noting that ICPS_TREASURY_TRANSFER = 1 and SNS_TOKEN_TREASURY_TRANSFER = 2 should be verified against the SNS governance proto or Candid spec before the page ships.

7. get_sns_canisters_summary argument format flagged — Added <!-- Needs human verification --> comment noting that the record { update_canister_list = opt false } argument format should be verified against the SNS root canister's Candid interface.

8. topic field note added — After the AddGenericNervousSystemFunction ID reservation note, added a paragraph explaining that the GenericNervousSystemFunction record accepts an optional topic : opt Topic field for categorizing custom proposals, and that omitting it is valid.

9. <!-- Upstream: --> comment updated — Removed the dfinity/examples — rust/stake_neuron_from_cli entry since the page no longer links to that example.

Items skipped

• ManageDappCanisterSettings section — Reviewer suggested "consider adding at least a brief mention." Not added in this pass. This is a new native proposal type not currently covered; adding it would be new content requiring source verification beyond the scope of feedback addressing. Filed as a follow-up suggestion for the next content iteration.

• Opening paragraph rewrite — Reviewer suggested starting with the action-oriented sentence rather than the "no single entity controls" framing. Skipped — this is a subjective style preference with no factual impact. The current opening is clear and readable.

• UpgradeSnsToNextVersion mention — Reviewer noted it is deprecated and its omission is defensible. No change made.

• RegisterExtension mention — Reviewer noted it is "under development" in portal. No change made; omission is correct for a production docs page.