NNS Updates 2025-03-07

[jasonzhu]

The NNS Team submitted the following proposals. DFINITY plans to vote on these proposals the following Monday.

https://dashboard.internetcomputer.org/proposal/135702

Proposals to be Submitted

Governance

# Upgrade the Governance Canister to Commit 7286063

__Proposer__: jason.zhu at dfinity.org

__Source code__: [7286063eaecd4d3625a8bf991213e27e21d3c2cf][new-commit]

[new-commit]: https://github.com/dfinity/ic/tree/7286063eaecd4d3625a8bf991213e27e21d3c2cf


## Features & Fixes

###  Added

* Collect metrics about timer tasks defined using ic_nervous_system_timer_task library.
* Re-enable neuron migration to stable memory:
  * Setting `MIGRATE_ACTIVE_NEURONS_TO_STABLE_MEMORY` to true, which will cause active neurons
  to be continously moved from heap memory to stable memory.
  * Compared to the last time it was enabled, several improvements were made:
    * Distribute rewards is moved to timer, and has a mechanism to distribute in batches in
    multiple messages.
    * Unstaking maturity task has a limit of 100 neurons per message, which prevents it from 
    exceeding instruction limit.
    * The execution of `ApproveGenesisKyc` proposals have a limit of 1000 neurons, above which
    the proposal will fail.
    * More benchmarks were added.
* Enable timer task metrics for better observability.

###  Changed

* Voting Rewards will be scheduled by a timer instead of by heartbeats.
* Unstaking maturity task will be processing up to 100 neurons in a single message, to avoid
  exceeding the instruction limit in a single execution.
* Voting Rewards will be distributed asynchronously in the background after being calculated.  
  * This will allow rewards to be compatible with neurons being stored in Stable Memory. 
* Ramp up the failure rate of _pb method to 0.7 again.

###  Fixed

* Avoid applying `approve_genesis_kyc` to an unbounded number of neurons, but at most 1000 neurons.


## New Commits

```
$ git log --format="%C(auto) %h %s" ebb190bf1da0dba3e486b78c95cf5a3c5542e2f3..7286063eaecd4d3625a8bf991213e27e21d3c2cf --  ./rs/nns/governance ./rs/sns/init
 7286063eae feat(nns): Enable timer task metrics (#4285)
 69cab5d235 feat(nns): Re-enable neuron migration (#4274)
 5ed21c21b5 perf(nns): Add benchmarks for with_neuron_mut (#4265)
 8ba19cdab4 fix(nns): Avoid applying approve_genesis_kyc for more than 1000 neurons (#4273)
 1385e1e466 feat(nns): Increase the _pb method failure rate to 0.7 again (#4237)
 a04682c0a5 chore(sns): Remove obsolete field `airdrop_distribution` (#4239)
 22f7b0b127 feat(governance): Scalable Voting Rewards (#4213)
 4846749e5d chore(sns): Obsolete airdrop neurons from initial SNS configuration (#4137)
 9d95c7c523 feat(nns): Limit the number of neurons to unstake maturity in a single message (#4184)
 7344d0ada2 perf(nns): Assert the instructions of certain periodic tasks are not too high (#4214)
 1d1c1e73bd test(nns): Fix tests that see less and less voting power. (#4196)
 90a8aa927f feat(governance): Move Rewards Distribution into timer (#3969)
 c628bfffcb chore(nns/sns): Update changelog for NNS/SNS releases (#4207)
 0d5ed6da44 feat(nns): Add metrics collection to timer tasks (#4141)
```


## Current Version

__Current git hash__: ebb190bf1da0dba3e486b78c95cf5a3c5542e2f3

__Current wasm hash__: d1668a798dc235587dfd3d50c0f7655b74d9360d4a5dbafd11ddc47042a7fbe4


## Verification

See the general instructions on [how to verify] proposals like this. A "quick
start" guide is provided here.

[how to verify]: https://github.com/dfinity/ic/tree/7286063eaecd4d3625a8bf991213e27e21d3c2cf/rs/nervous_system/docs/proposal_verification.md


### WASM Verification

See ["Building the code"][prereqs] for prerequisites.

[prereqs]: https://github.com/dfinity/ic/tree/7286063eaecd4d3625a8bf991213e27e21d3c2cf/README.adoc#building-the-code

```
# 1. Get a copy of the code.
git clone git@github.com:dfinity/ic.git
cd ic
# Or, if you already have a copy of the ic repo,
git fetch
git checkout 7286063eaecd4d3625a8bf991213e27e21d3c2cf

# 2. Build canisters.
./ci/container/build-ic.sh -c

# 3. Fingerprint the result.
sha256sum ./artifacts/canisters/governance-canister.wasm.gz
```

This should match `wasm_module_hash` field of this proposal.

[1eo]

Adopt proposal 135702

---

Proposal

• Canister id rrkah-fqaaa-aaaaa-aaaaq-cai is indeed the governance canister.
• The upgrade args correspond to the empty args.
• The install mode is indeed upgrade.
• The wasm hash is reproducible.

---

Code Review

Added Features

1. Timer Task Metrics: Added via ic_nervous_system_timer_task library for better observability of timer-based operations. No external API changes; low vulnerability risk.
2. Neuron Migration to Stable Memory: Enabled by default with improvements like timer-based reward distribution, 100 neuron unstaking limit per message, 1000 neuron cap for ApproveGenesisKyc, and new benchmarks. Enhances scalability and persistence; no breaking API changes, but migration complexity requires robust error handling.
3. Disburse Maturity API: Added to governance.proto as a non-breaking, unimplemented feature for future use. No vulnerabilities.

Changed Behaviors

1. Voting Rewards: Shifted to timer-based from heartbeats for better scheduling control; internal change, low risk.
2. Unstaking Maturity: Limited to 100 neurons per message to fit WebAssembly constraints; internal, needs edge-case handling.
3. Async Reward Distribution: Now background-processed in batches, improving scalability with stable memory. Internal change; risks include race conditions and state consistency.
4. _pb Method Deprecation: Failure rate increased from 0.1 to 0.7 to push migration to newer methods. Soft breaking change; requires user communication.

Deprecated Features

• NnsCanisterUpgrade/NnsRootUpgrade: Marked obsolete, no immediate impact.

Fixed Issues

• ApproveGenesisKyc Limit: Capped at 1000 neurons to prevent resource exhaustion, improving security. Internal change; fails proposals exceeding limit.

High-Level Assessment

• API: Mostly internal changes; _pb method failures are the main user-facing impact.
• Quality: Focuses on scalability, observability, and performance; high quality with solid design.
• Vulnerabilities: Migration and async operations need strong error handling and testing for consistency.

[cyberowl]

proposal - 135702 – Cyberowl | CodeGov

Checks

Vote: ADOPT
Hash Match: MATCH
Feedback: NONE
Proposer Check: MATCH
Target Canister: MATCH
Reason:
Build completed successfully, hashes are verified, and commits match the changes described with the code implemented.

Summary:

The upgrade incorporates enhanced metrics collection for timer tasks and re-enables neuron migration from heap to stable memory, ensuring improved observability and reliability. It introduces asynchronous reward distribution via a timer and imposes limits on neuron processing in tasks like unstake maturity and approve_genesis_kyc to prevent exceeding instruction limits.

Commits Summary

7286063eae
New function to encode timer task metrics using the existing MetricsRegistry and integrates it into the main metrics endpoint, while also updating the seeding task name to lowercase for naming consistency.

69cab5d235
Unconditionally enables neuron migration from heap to stable memory by setting the migration flag to true, with integration tests now verifying that neurons reside in stable memory instead of the heap.

5ed21c21b5
Renames the NeuronLocation enum to NeuronActiveness (with variants Active and Inactive) for clearer semantics and expands the benchmarking suite to explicitly test both heap and stable memory scenarios, adding new benchmarks and helper functions to assess various neuron mutation patterns.

8ba19cdab4
Refactors approve_genesis_kyc by moving it from Governance to NeuronStore and adding a cap of 1000 neurons, ensuring that the operation remains within safe instruction limits and returns explicit errors when exceeded.

1385e1e466
Matches description Increase the _pb method failure rate to 0.7 again .

a04682c0a5
Removes the deprecated airdrop distribution functionality from SNS initialization by deleting the corresponding Protobuf message.

22f7b0b127
Refactors reward distribution in the NNS governance canister to operate asynchronously by introducing a RewardsDistribution structure and scheduling pending rewards using a timer-based task that persists data in stable memory. This change batches rewards to prevent exceeding instruction limits, enhances scalability and reliability for large neuron sets, and is supported by comprehensive tests and benchmarks.

4846749e5d
Removes the support for airdrop distribution from SNS initialization. It deletes the AirdropDistribution message and the airdrop_distribution field from the protocol definitions, removes all related validation and test logic, and cleans up the configuration.

9d95c7c523
Updates the unstake maturity process by adding a max_num_neurons parameter (defaulting to 100) to both unstake_maturity_of_dissolved_neurons and list_neurons_ready_to_unstake_maturity, ensuring that only a limited batch of neurons is processed per execution.

7344d0ada2
New benchmark utility function, check_projected_instructions, which scales benchmark instruction counts to production levels and asserts they stay under a 25B instruction limit to catch potential instruction limit violations early.

1d1c1e73bd
Updates the governance initialization by adding a timestamp for voting power refresh (voting_power_refreshed_timestamp_seconds) to each initial neuron, using the current system time rather than a default value.

90a8aa927f
Implements asynchronous timer-based reward distribution by introducing a new timer library ic-nervous-system-timers that wraps ic-cdk-timers. It decouples reward distribution from the heartbeat by scheduling a recurring reward distribution task that dynamically calculates delays based on previous events.

c628bfffcb
Refactor the BUILD.bazel file for the ic-state-manager package by consolidating dependencies into named lists (DEPENDENCIES, DEV_DEPENDENCIES, BIN_DEPENDENCIES) for better organization and reuse across targets. Unnecessary dependencies like ic-sys and ic-registry-routing-table removed.

0d5ed6da44
Metrics collection for timer tasks by adding new metric structures that track execution details such as instruction usage, start/finish times, and histograms with 29 buckets, capturing data up to 10 trillion instructions. It integrates these metrics into both synchronous and asynchronous timer tasks.

If you like the review please follow:

About CodeGov…(click to expand)

CodeGov has a team of developers who review and vote independently on the following proposal topics: IC-OS Version Election, Protocol Canister Management, Subnet Management, Node Admin, and Participant Management. The CodeGov NNS known neuron is configured to follow our reviewers on these topics and Synapse on most other topics. We strive to be a credible and reliable Followee option that votes on every proposal and every proposal topic in the NNS. We also support decentralization of SNS projects such as WaterNeuron and KongSwap with a known neuron and credible Followees.

Learn more about CodeGov and it’s mission at codegov.org.

[ZackDS]

to be edited

[LaCosta]

Proposal 135702 – LaCosta | CodeGov

Vote: ADOPT

Governance Canister

Reason:
Build successful and hashes match, commits look great and match the description. Found no issues.

[7286063eae]: Adds a call to the new function encode_timer_task_metrics in the encode_metrics function, which appends it to the response MetricsEncoder in order to be encoded into the /metrics endpoint.

[69cab5d235]: Re enable neuron migration from heap to stable memory by setting the migration flag MIGRATE_ACTIVE_NEURONS_TO_STABLE_MEMORY to true.

[5ed21c21b5]: Change enum NeuronLocation to NeuronActiveness and fields Heap and Stable to Active and Inactiverespectively. Add new benchmarkswith_neuron_mut` for both stable and in heap neurons.

[8ba19cdab4]: New method approve_genesis_kyc limits the number of neurons that can change their KYC status to 1000 at a time.

[1385e1e466]: Increases the probability of depecrated methods manage_neuron_pb and list_neurons_pb back to 0.7 since this was only reduced to give time to integrators to migrate.

[a04682c0a5]: Removes obsolete field airdrop_distribution.

[22f7b0b127]: New logic for reward distribution when neurons are in stable memory, changing the reward distribution to be asynchronous by dividing the messages into batches limited to 1 billion.

[4846749e5d]: Obsoletes and thus removes support for airdrop distribution from the initial SNS configuration.

[9d95c7c523]: Sets a new limit for the number of neurons allowed to unstake their maturity in a single execution. A constant MAX_NEURONS_TO_UNSTAKE currently defaulted to 100 is used to store the value and is passed down from the function unstake_maturity_of_dissolved_neurons onwards to set this limit.

[7344d0ada2]: Implements a new function check_projected_instructions in the new file rs/nns/governance/src/benches_util.rs used to check that the total instructions from the benchmarks results scaled to production, are below a given instructions_limit that in all the cases used was set to 25_000_000_000.

[1d1c1e73bd]: Instead of using a hardcoded value for voting_power_refreshed_timestamp_seconds since this was causing tests to fail because the clock of the test was set to the current real time. Since a lot of tests apply this logic to time and run ok, it was decided to change this hardcoded value was set to the current time aswell.

[90a8aa927f]: Creates a new file rs/nns/governance/src/timer_tasks/reward_distribution.rs responsible for hosting the logic for calculating the delay for each run of the reward distrubtion and running the async task CalculateDistributableRewardsTask for calculating the distribution of this rewards.

[c628bfffcb]: Updates the changelogs to incorporate released proposals.

[0d5ed6da44]: Introduces metrics for both async and sync tasks for schedulers. The new file rs/nervous_system/timer_task/src/metrics.rs holds all the necessary structs and functions to be used, for recording the schedulers instruction count, start/finish times (for async) and usage of a INSTRUCTION_BUCKETS with to 29 buckets of instruction counts to record instruction, the maximum of which is u64::MAX. The functions with_async_metrics and with_sync_metrics are used to record the metrics for each type of task the scheduler is recording.

About CodeGov

CodeGov has a team of developers who review and vote independently on the following proposal topics: IC-OS Version Election, Protocol Canister Management, Subnet Management, Node Admin, and Participant Management. The CodeGov NNS known neuron is configured to follow our reviewers on these technical topics. We also have a group of Followees who vote independently on the Governance and the SNS & Neuron’s Fund topics. We strive to be a credible and reliable Followee option that votes on every proposal and every proposal topic in the NNS. We also support decentralization of SNS projects such as WaterNeuron, KongSwap, and Alice with a known neuron and credible Followees.

Learn more about CodeGov and its mission at codegov.org.

[Zane]

Proposal 135702 - Zane | CodeGov

Vote: ADOPT
Reason: Build completes successfully, both hashes and reviewed commits match their descriptions.

7286063eae Modified encode_metrics method to encode timer task related metrics fetched from the METRICS_REGISTRY so they can be exposed through the /metrics endpoint.

69cab5d235 Set MIGRATE_ACTIVE_NEURONS_TO_STABLE_MEMORY to true and updated asserts in test_neuron_migration_from_heap_to_stable since with this change heap neuron count is always 0.

5ed21c21b5 Added various benchmarks to obtain insights on number of instruction used when calling with_neuron_mut using different neuron storage configurations while modifying only the neuron stake and all neuron sections. Renamed NeuronLocation enum to NeuronActiveness and its variants Heap/Stable to Active/Inactive respectively.

8ba19cdab4 Limit ApproveGenesisKyc proposals to only update KYC status for 1000 neurons at a time. If this limit is exceeded an error is returned.

1385e1e466 Bumped panic probability for manage_neuron_pb and list_neurons_pb to 0.7 again in order to incentivate migrations to the new endpoints.

a04682c0a5 Removed airdrop_distribution field from FractionalDeveloperVotingPower and deleted related AirdropDistribution type definition.

22f7b0b127 Refactored rewards distribution so that it can be spread across multiple messages. When distribute_rewards is called, instead of processing all neurons, a reward distribution event is added to the RewardsDistributionStateMachine. Then a timer is scheduled to perform the distribution, starting from the last pending distribution in the state machine or any backlogged reward events, if present. Each task execution is capped to 1B instructions, after which processing is temporarily paused and scheduled to run again after a 2 seconds interval, the timer keeps going until there are distribution events left to be processed in the state machine, when all work is complete the task is finally cleared.

4846749e5d Deleted airdrop distribution of neurons from the initial_token_distribution in the SNSInitPayload.

9d95c7c523 In unstake_maturity_of_dissolved_neurons limited the number of neurons to unstake maturity for to 100 by passing down MAX_NEURONS_TO_UNSTAKE to list_neurons_ready_to_unstake_maturity, which uses this value to read at most the specified amount of neurons from the neuron store.

7344d0ada2 Added check_projected_instructions helper function to check instructions used by the benchmark do not exceed the given limit when scaled to values used on mainnet. Updated many benchmarks to make use of it to catch potential problematic operations early.

1d1c1e73bd Prevent voting power reduction kicking in for tests relying on with_test_neurons_impl by setting current timestamp as neurons’ last voting power refresh.

90a8aa927f Make use of timer tasks for reward distribution events instead of heartbeats.

c628bfffcb Updated changelogs.

0d5ed6da44 Collect various timer tasks related metrics into METRICS_REGISTRY.

About CodeGov

CodeGov has a team of developers who review and vote independently on the following proposal topics: IC-OS Version Election, Protocol Canister Management, Subnet Management, Node Admin, and Participant Management. The CodeGov NNS known neuron is configured to follow our reviewers on these technical topics. We also have a group of Followees who vote independently on the Governance and the SNS & Neuron’s Fund topics. We strive to be a credible and reliable Followee option that votes on every proposal and every proposal topic in the NNS. We also support decentralization of SNS projects such as WaterNeuron, KongSwap, and Alice with a known neuron and credible Followees.

Learn more about CodeGov and its mission at codegov.org.