pallet-referenda: Migrate from Currency reserves to fungible holds #10701

Krayt78 · 2025-12-19T15:47:53Z

Summary

This PR migrates pallet-referenda from the deprecated Currency trait with anonymous reserves to the modern fungible traits with typed holds, bumping the storage version from v1 to v2. This is part of the umbrella task #226.

Changes

Config Updates

Replaced Currency with NativeBalance using the new fungible traits:
- fungible::Inspect
- fungible::Mutate
- fungible::Balanced
- fungible::InspectHold
- fungible::MutateHold
Added HoldReason::DecisionDeposit composite enum for tracking deposit holds with a specific reason

Storage Migration (v1 → v2)

Added MigrateV1ToV2<T, I, OldCurrency> migration that:

Iterates through all existing referenda (Ongoing, Approved, Rejected, Cancelled, TimedOut)
For each deposit (submission and decision deposits):
- Unreserves the old anonymous reserved balance using the legacy ReservableCurrency trait
- Places a new hold with HoldReason::DecisionDeposit using the new MutateHold trait
Updates storage version from 1 to 2

The migration gracefully handles edge cases:

Skips execution if not on version 1
Logs warnings if unreserve is incomplete
Logs errors if hold placement fails
Properly handles Killed referenda (no deposits to migrate)
Includes try-runtime hooks for pre/post upgrade verification

Runtime Integration

To use this migration in your runtime:

pub type Migrations = (
    pallet_referenda::migration::v2::MigrateV1ToV2<Runtime, (), Balances>,
);

Testing

Added comprehensive test coverage:

migration_v1_to_v2_works - Tests full migration flow with multiple referendum types (Ongoing, Approved, TimedOut)
migration_v1_to_v2_skips_if_not_v1 - Verifies migration is skipped when not on version 1
migration_v1_to_v2_handles_killed_referendum - Tests handling of killed referenda with no deposits

Checklist

My PR includes a detailed description as outlined in the "Description" and its two subsections above.
My PR follows the labeling requirements of this project (at minimum one label for T required)
- External contributors: Use /cmd label <label-name> to add labels
- Maintainers can also add labels manually
I have made corresponding changes to the documentation (if applicable)
I have added tests that prove my fix is effective or that my feature works (if applicable)

Krayt78 · 2025-12-19T15:54:21Z

/cmd label T2-pallets

…r I, updating related usages in the NativeBalance methods.

…ntimes

Krayt78 · 2025-12-19T16:57:53Z

There is a runtime type mismatch now
The Slash type now expects OnUnbalanced<DebtOf<Self, I>> where DebtOf is a fungible Debt (not the old NegativeImbalance).

This means we need to migrate treasury first to use Fungible before this one.

gui1117 · 2026-01-03T03:05:35Z

There is a runtime type mismatch now The Slash type now expects OnUnbalanced<DebtOf<Self, I>> where DebtOf is a fungible Debt (not the old NegativeImbalance).

This means we need to migrate treasury first to use Fungible before this one.

That mean we need to upgrade both together, because otherwise pallet-referenda won't support pallet-treasury for slash destination.

IMO we can make treasury Currency type bind both Currency and Fungible and implement both OnUnbalanced<Debt> and OnUnbalanced<NegativeImbalance>. Because pallet-balances support both traits so it is compatible.

gui1117 · 2026-01-03T03:07:47Z

substrate/frame/referenda/src/lib.rs

 			>;
 		/// Currency type for this pallet.
-		type Currency: ReservableCurrency<Self::AccountId>;
+		type NativeBalance: Inspect<Self::AccountId>


IMO better to keep the same old name Currency. It is still a kind of currency type, the underlying traits are fungible but this is fine. Most users won't see the difference as pallet-balances implements both. And if it breaks the compile error will be fine.

gui1117 · 2026-01-03T03:15:20Z

substrate/frame/referenda/src/lib.rs

+				&HoldReason::<I>::DecisionDeposit.into(),
+				&who,
+				amount,
+				Precision::Exact,


we should use Precision::BestEffort, we don't want to prevent a kill from happening because the slash is failing for some reason.

gui1117 · 2026-01-03T03:19:26Z

substrate/frame/referenda/src/lib.rs

+			Self::slash_deposit(Some(status.submission_deposit.clone()))?;
+			Self::slash_deposit(status.decision_deposit.clone())?;


I don't really like that this can return an error here. We don't want to block the kill if for some reason the slash fails. Also fungible API never really specifies why it could fail. In the other comment I say to change to BestEffort to make this scenario less likely but still strictly speaking it doesn't prevent the slash from failing, so maybe better to actually ignore the error.

Suggested change

Self::slash_deposit(Some(status.submission_deposit.clone()))?;

Self::slash_deposit(status.decision_deposit.clone())?;

let _ = Self::slash_deposit(Some(status.submission_deposit.clone())).inspect(/* log some error or something */);

let _ = Self::slash_deposit(status.decision_deposit.clone()).inspect(/* log some error or something */);

gui1117 · 2026-01-03T03:23:01Z

substrate/frame/referenda/src/migration.rs

+			if on_chain_version != 1 {
+				log::warn!(target: TARGET, "skipping migration from v1 to v2.");
+				return weight;
+			}


you can use versioned migration to factorize out those checks: e.g.

polkadot-sdk/substrate/frame/staking/src/migrations.rs

Lines 147 to 153 in 0433400

pub type MigrateV15ToV16<T> = VersionedMigration<

15,

16,

VersionUncheckedMigrateV15ToV16<T>,

Pallet<T>,

<T as frame_system::Config>::DbWeight,

>;

gui1117 · 2026-01-03T03:25:09Z

substrate/frame/referenda/src/migration.rs

+			let mut migrated_deposits = 0u32;
+
+			for (index, info) in v1::ReferendumInfoFor::<T, I>::iter() {
+				weight.saturating_accrue(T::DbWeight::get().reads(1));


is it fine to do like this? T::DbWeight::get().reads(1) only returns the ref_time weight and ignores the proof_size weight.

gui1117 · 2026-01-03T03:31:38Z

substrate/frame/referenda/src/migration.rs

+			for (index, info) in v1::ReferendumInfoFor::<T, I>::iter() {
+				weight.saturating_accrue(T::DbWeight::get().reads(1));
+
+				let deposits_to_migrate = Self::collect_deposits(&info);


There is no way for an attacker to start submitting small deposits and make this too big, isn't it? otherwise we should do a multi block migration.

Krayt78 added 8 commits December 19, 2025 10:56

started migration to fungible

c312c30

fixed tests

b3e6836

fmt

26431c0

fixed becnhmarking files

ae8f38e

startign migration file

9d6e9b9

Add migration tests for upgrading from v1 to v2

8d26843

fixed test case

0a4346d

fmt

8aa1740

Krayt78 requested a review from a team as a code owner December 19, 2025 15:47

paritytech-cmd-bot-polkadot-sdk bot added the T2-pallets This PR/Issue is related to a particular pallet. label Dec 19, 2025

Krayt78 added 3 commits December 19, 2025 17:10

updated runtimes

2bf531f

Refactor HoldReason enum to be generic over the runtime type paramete…

426ae1a

…r I, updating related usages in the NativeBalance methods.

Update Currency type to NativeBalance in ambassador and fellowship ru…

0433400

…ntimes

gui1117 reviewed Jan 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

pallet-referenda: Migrate from Currency reserves to fungible holds #10701

pallet-referenda: Migrate from Currency reserves to fungible holds #10701

Uh oh!

Krayt78 commented Dec 19, 2025 •

edited

Loading

Uh oh!

Krayt78 commented Dec 19, 2025

Uh oh!

Krayt78 commented Dec 19, 2025

Uh oh!

gui1117 commented Jan 3, 2026

Uh oh!

gui1117 Jan 3, 2026

Uh oh!

gui1117 Jan 3, 2026

Uh oh!

gui1117 Jan 3, 2026

Uh oh!

gui1117 Jan 3, 2026

Uh oh!

gui1117 Jan 3, 2026

Uh oh!

gui1117 Jan 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		Self::slash_deposit(Some(status.submission_deposit.clone()))?;
		Self::slash_deposit(status.decision_deposit.clone())?;

	pub type MigrateV15ToV16<T> = VersionedMigration<
	15,
	16,
	VersionUncheckedMigrateV15ToV16<T>,
	Pallet<T>,
	<T as frame_system::Config>::DbWeight,
	>;

pallet-referenda: Migrate from Currency reserves to fungible holds #10701

Are you sure you want to change the base?

pallet-referenda: Migrate from Currency reserves to fungible holds #10701

Uh oh!

Conversation

Krayt78 commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Config Updates

Storage Migration (v1 → v2)

Runtime Integration

Testing

Checklist

Uh oh!

Krayt78 commented Dec 19, 2025

Uh oh!

Krayt78 commented Dec 19, 2025

Uh oh!

gui1117 commented Jan 3, 2026

Uh oh!

gui1117 Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

gui1117 Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

gui1117 Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

gui1117 Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

gui1117 Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

gui1117 Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Krayt78 commented Dec 19, 2025 •

edited

Loading