Introduce Vaults pallet (part of the pUSD Project) by lrazovic · Pull Request #10699 · paritytech/polkadot-sdk

lrazovic · 2025-12-19T15:14:47Z

Description

This PR introduces pallet-vaults, a new FRAME pallet that implements a Collateralized Debt Position (CDP) system for creating over-collateralized stablecoin loans on Substrate-based blockchains. The pallet allows users to lock up DOT as collateral and mint pUSD against it.

Integration

For Runtime Developers

To integrate pallet-vaults into your runtime:

Add dependency to your runtime's Cargo.toml:

pallet-vaults = { version = "0.1.0", default-features = false }

Implement the Config trait in your runtime:

impl pallet_vaults::Config for Runtime {
    type Currency = Balances;                    // Native token for collateral
    type RuntimeHoldReason = RuntimeHoldReason;
    type Asset = Assets;                         // pallet-assets for pUSD
    type AssetId = u32;
    type TimeProvider = Timestamp;
    type Oracle = OraclePallet;                  // Must implement `ProvidePrice` trait
    type AuctionsHandler = Auctions;             // Liquidation auction handler
    type FeeHandler = ResolveTo<Treasury, Balances>;   // DOT from surplus auctions
    type SurplusHandler = ResolveTo<Treasury, Assets>; // pUSD surplus transfers
    type ManagerOrigin = EnsureVaultsManager;    // Governance (returns VaultsManagerLevel)
    type WeightInfo = pallet_vaults::weights::SubstrateWeight<Runtime>;
    #[cfg(feature = "runtime-benchmarks")]
    type BenchmarkHelper = VaultsBenchmarkHelper;
    type StablecoinAssetId = StablecoinAssetId;  // pUSD asset ID
    type InsuranceFund = InsuranceFund;          // Account receiving protocol revenue
    type MaxOnIdleItems = ConstU32<100>;         // Safety limit for on_idle processing
    type CollateralLocation = CollateralLocation; // XCM Location of collateral asset
}

Add to construct_runtime!:

construct_runtime!(
  pub enum Runtime {
    // ... other pallets
    Vaults: pallet_vaults,
  }
);

For existing chains, include the migration:

pub type Migrations = (
   pallet_vaults::migrations::MigrateV0ToV1<Runtime, VaultsInitialConfig>,
);

For Pallet Developers

Other pallets can interact with vaults via the CollateralManager trait:

use sp_pusd::CollateralManager;

// Get current DOT price from oracle
if let Some(price) = <pallet_vaults::Pallet<T> as CollateralManager<AccountId>>::get_dot_price() {
  // Use the price data
}

// Execute a purchase during auction
CollateralManager::execute_purchase(buyer, collateral, payment, recipient, vault_owner)?;

Review Notes

Key Features

Per-Account Vaults: Each account can have at most one vault. Collateral is held in the user's account via MutateHold (not transferred to a pallet account)
Over-Collateralization: Two-tier ratio system - Initial CR for minting/withdrawing (e.g., 200%) and Minimum CR as liquidation threshold (e.g., 180%)
Stability Fees: Time-based interest accrual using timestamps. Interest is minted to the Insurance Fund when it accrues ("mint-on-accrual" model).
Liquidation System: Unsafe vaults can be liquidated by anyone, with collateral auctioned via AuctionsHandler
Bad Debt Tracking: Records shortfalls when auctions fail to cover debt, healable via heal() extrinsic
Tiered Governance: Full privileges for all parameters, Emergency privileges for defensive actions only (lowering debt ceiling)

Vault Lifecycle:

create_vault - Create a new Vault and lock initial collateral
deposit_collateral / withdraw_collateral - Manage collateral
mint - Borrow pUSD against collateral
repay - Burn pUSD to reduce debt (interest paid first)
close_vault - Close debt-free vault, release collateral
liquidate_vault - Liquidate unsafe vaults
poke - Force fee accrual on any vault

Hold Reasons:

VaultDeposit - Collateral backing active vaults
Seized - Collateral under liquidation, pending auction

Testing

The pallet includes comprehensive tests covering:

Vault creation, deposits, withdrawals, and closure
Minting and repayment with interest accrual
Collateralization ratio enforcement
Liquidation flow and auction integration
Oracle staleness handling
Governance parameter updates
Migration from V0 to V1

cla-bot-2021 · 2025-12-19T15:14:55Z

User @lrazovic, please sign the CLA here.

Waiting to generate the weights after the implementation is approved.

bkchr · 2025-12-22T10:19:00Z

substrate/frame/vaults/src/lib.rs

+	/// 365.25 days × 24 hours × 60 minutes × 60 seconds × 1000 milliseconds = 31,557,600,000
+	const MILLIS_PER_YEAR: u64 = 31_557_600_000;


Just put the calculation here instead of having it in a comment.

Addressed in 054c6e6.

bkchr · 2025-12-22T10:21:47Z

substrate/frame/vaults/src/lib.rs

+				// Cannot close a vault that's being liquidated
+				ensure!(vault.status == VaultStatus::Healthy, Error::<T>::VaultInLiquidation);
+
+				// Update fees


Please tell claude to not over comment stuff. The function name is descriptive enough.

bkchr · 2025-12-22T10:27:01Z

substrate/frame/vaults/src/lib.rs

+		/// This ensures the Insurance Fund account is created with a provider reference so it can
+		/// receive any amount (including below ED) without risk of being reaped.
+		fn on_runtime_upgrade() -> Weight {
+			let on_chain_version = StorageVersion::get::<Pallet<T>>();
+
+			if on_chain_version < 1 {
+				Self::ensure_insurance_fund_exists();
+				StorageVersion::new(1).put::<Pallet<T>>();
+
+				log::info!(
+					target: LOG_TARGET,
+					"Migrated storage from version {:?} to 1",
+					on_chain_version
+				);
+
+				// Weight: 1 read (storage version) + 1 read (account_exists) + 2 writes
+				// (inc_providers + storage version)
+				T::DbWeight::get().reads_writes(2, 2)
+			} else {
+				log::debug!(
+					target: LOG_TARGET,
+					"No migration needed, on-chain version {:?}",
+					on_chain_version
+				);
+				// Weight: 1 read (storage version check)
+				T::DbWeight::get().reads(1)
+			}
+		}


This should be some extra code in the runtime when we add this pallet.

Removed in 65030aa.

bkchr · 2025-12-22T10:31:02Z

substrate/frame/vaults/src/lib.rs

+			// Update cursor for next block
+			match last_processed {
+				Some(last) => {
+					if Vaults::<T>::iter_from(Vaults::<T>::hashed_key_for(&last)).nth(1).is_none() {


So we are doing one more iteration that isn't part of the weight? Maybe we should just do this at the top of the function.

Reworked a bit in 054c6e6.

bkchr · 2025-12-22T10:35:01Z

substrate/frame/vaults/src/lib.rs

+						remaining_collateral,
+						total_obligation,
+					)?
+					.expect("total_obligation is non-zero; qed");


Not really a problem to convert this into an error, better safe than sorry here.

Converted the .expects into errors in 054c6e6.

substrate/frame/vaults/src/lib.rs

bkchr · 2025-12-22T10:59:09Z

substrate/frame/support/src/traits/tokens/stable.rs

Not sure why these types are not part of the vault crate right now. This code should be clearly not be in this folder.

These types will be reused by the other pallets in the pUSD family. Currently they're only used by this pallet, but once we start adding the other pallets, they'll be imported from this common crate. If you have a suggestion for better placement, I'm happy to move them accordingly!

Substrate is not the right place for these items. For Frame pallets common items usually located under support crate. But these traits and types I would locate for now next to their implementations. Later if we have impls for them, we modify them if needed and move to support. But for now I would keep it simple.

we still need to move this under frame

Jan-Jan · 2025-12-22T11:59:56Z

substrate/bin/node/runtime/src/lib.rs

+	}
+}
+
+/// Mock oracle adapter that provides a fixed price for noe.


Fixed in ff5479b.

…vaults

substrate/frame/vaults/src/lib.rs

muharem

reviewed the implementation, have not checked the tests and the benchmarks. gonna continue tomorrow.

muharem · 2026-02-16T10:11:09Z

substrate/frame/vaults/src/lib.rs

+		type AssetId: Parameter + Member + Copy + MaybeSerializeDeserialize + MaxEncodedLen;
+
+		/// Time provider for fee accrual using UNIX timestamps.
+		type TimeProvider: Time;


we do not have a working time provider solution. if you have not too, we need to migrate this into block provider. The block provider should be configurable type. You can check society pallet for an example.

We actually started with block numbers, but we switched to timestamps (via pallet-timestamps) because the interest accrual domain benefits from real time rather than block-number-as-proxy

its accuracy is prev_timestamp + 3sec < current_timestamp > prev_timestamp + 30sec. not that great, and relies on prev timestamp value. I do not know a case where we used it. I would not do it with this pallet if we do not really know what are we doing.

actually that ^ accuracy only applicable for Relay Chain. for Asset Hubs that 3 sec is 0. tho we probably can pass timestamps from RC to AH, but only from the RC block AH building its current block.

if we use block numbers, on AH its gonna be RC block numbers too.

cc: @kianenigma @seadanda

Using the AH Timestamp, until AH collators are the same as RC validators (something that is envisioned long term) is a no-go IMO. It is way too little security.

Using the relay Timestamp is IMO a good option. It is ultimately an oraclized value that the runtime can never know exactly what it is, but relying on the validators is as good as it gets. I was under the impression that the Relay Timestamp is part of the PersistedValidationData, but it is not. The state root is, and we can use a state-proof against that. Not ideal though. If we are to use this, I would explore doing it properly and via #6235

Relay block number is also a safe Plan B. although it has its own set of trade-offs: If we ever ever change the relay block time, all hell breaks loose. Kusama/JAM is already being toyed with having shorter relay slots.

Verdict:

Dispatch claude with a good prompt to fix Customize-able ParacnainInherentDataProvider #6235. If not overly complicated, this feature will help multiple systems.

If not straightforward, then use relay timestamp

AH timestamp not a viable option IMO.

If I understand correctly, paritytech/polkadot-sdk#10678 introduced a KeyToIncludeInRelayProof runtime API that lets parachains request arbitrary relay chain storage keys in the inherent proof. Building on that, accessing the RC Timestamp should now be straightforward. A first draft (untested) is available here: https://gist.github.com/lrazovic/bf701015bcc8e482207c1034b5b7a346

Nice, without looking at the gist, the approach sounds exactly correct to me.

substrate/frame/vaults/src/lib.rs

muharem · 2026-02-16T10:40:56Z

substrate/frame/vaults/src/lib.rs

+				let total_issuance = T::Asset::total_issuance(T::StablecoinAssetId::get());
+				ensure!(
+					total_issuance.saturating_add(amount) <=
+						MaximumIssuance::<T>::get().ok_or(Error::<T>::NotConfigured)?,


should we have some type to get PSM reserved capacity and subtract it?

we can do this when we locate PsmInterface trait in frame/support

muharem · 2026-02-16T10:59:31Z

substrate/frame/vaults/src/lib.rs

+			vault.accrued_interest.saturating_accrue(accrued);
+			vault.last_fee_update = now;


I think I can update my vault lets say every block and have accrued always set to 0 and last_fee_update to now.

Good catch, addressed and tested in f1a9638

if StabilityFee updated at now, it takes effect for the vaults from last_fee_update, not from now. right? is this expected?

For correctness, In 97d0989 I introduced a PreviousStabilityFee storage item that lets update_vault_fees split interest accrual at the fee change boundary, so the old rate applies before the change and the new rate only applies after it

substrate/frame/vaults/src/lib.rs

muharem · 2026-02-16T11:55:08Z

substrate/frame/vaults/src/lib.rs

+
+			Self::deposit_event(Event::BadDebtRepaid { amount: burned });
+
+			Ok(())


we can make this call for free if there was anything to burn

Done in cdb14d6

its should be for free only if the execution really healed some amount. like its done for liquidate_vault call.

Updated in 1868737

substrate/frame/vaults/src/lib.rs

muharem · 2026-02-23T08:45:48Z

substrate/frame/support/src/traits/tokens/stable.rs

Substrate is not the right place for these items. For Frame pallets common items usually located under support crate. But these traits and types I would locate for now next to their implementations. Later if we have impls for them, we modify them if needed and move to support. But for now I would keep it simple.

substrate/frame/vaults/src/lib.rs

substrate/frame/vaults/src/tests.rs

substrate/frame/vaults/src/benchmarking.rs

substrate/frame/vaults/src/lib.rs

Gioyik · 2026-02-27T03:54:59Z

substrate/frame/vaults/src/lib.rs

+			if !keeper_incentive.is_zero() {
+				T::Asset::transfer(
+					T::StablecoinAssetId::get(),
+					&T::InsuranceFund::get(),
+					keeper,
+					keeper_incentive,
+					Preservation::Expendable,
+				)?;
+			}


this doesn't seem right to me, the keeper_incentive transfer using ? propagates any transfer failure, but all of the auction finalization logic, collateral release, CurrentLiquidationAmount decrement, bad-debt recording, and vault removal sits after this point. If the Insurance Fund has insufficient pUSD for the keeper payment, the entire complete_auction call exits early and none of those steps execute.

This seems to leave the vault permanently in VaultStatus::InLiquidation with collateral held under HoldReason::Seized and no way (not entirely sure if this is true) to finalize it. All user-callable vault operations gate on VaultStatus::Healthy, and there's no force_complete_auction or similar recovery extrinsic in the pallet.

The keeper payment should be non-blocking for auction finalization. One option is to attempt the transfer and, on failure, record the unpaid incentive for later settlement rather than aborting the whole completion. Something like:

if !keeper_incentive.is_zero() { let payment_result = T::Asset::transfer( T::StablecoinAssetId::get(), &T::InsuranceFund::get(), keeper, keeper_incentive, Preservation::Expendable, ); if let Err(_) = payment_result { // Record as owed; don't block finalization UnpaidKeeperIncentives::<T>::mutate(keeper, |owed| { owed.saturating_accrue(keeper_incentive); }); Self::deposit_event(Event::KeeperIncentiveDeferred { keeper: keeper.clone(), amount: keeper_incentive, }); } } // Finalization (collateral release, CLA decrement, vault removal) proceeds unconditionally

Alternatively, I am not sure if a governance-callable force_complete_auction extrinsic would make sense to provide a recovery path for any vault stuck in InLiquidation due to this or similar failures.

Good point, part of 389590f. But I'm not sure if adding a new UnpaidKeeperIncentives storage item for this edge-case makes sense, we just emit an event for now

substrate/frame/vaults/src/lib.rs

muharem · 2026-03-19T10:18:01Z

substrate/frame/vaults/src/lib.rs

+		/// The currency used for collateral (native DOT).
+		/// Collateral is managed via `pallet_balances` using holds.
+		/// The Balance type is derived from this and must implement `FixedPointOperand`.
+		type Currency: FungibleMutate<Self::AccountId, Balance: FixedPointOperand>


how about Collateral? Currency is outdated naming, refers more to Currency trait

Renamed in 6cef850

muharem · 2026-03-19T10:18:13Z

substrate/frame/vaults/src/lib.rs

+		/// The asset used for pUSD debt.
+		/// Constrained to use the same Balance type as Currency.
+		/// Also implements `Balanced` for creating credits during surplus transfers.
+		type Asset: FungibleMutate<Self::AccountId, Balance = BalanceOf<Self>>


How about StableAsset?

Renamed in 6cef850

feat: upstream pallet-vaults

56671cb

lrazovic requested a review from a team as a code owner December 19, 2025 15:14

seadanda self-requested a review December 19, 2025 15:59

seadanda added the T2-pallets This PR/Issue is related to a particular pallet. label Dec 19, 2025

seadanda requested a review from Overkillus December 19, 2025 16:17

chore: removed deprecated warning on SubstrateWeight.

49b0ae0

Waiting to generate the weights after the implementation is approved.

bkchr reviewed Dec 22, 2025

View reviewed changes

Jan-Jan reviewed Dec 22, 2025

View reviewed changes

lrazovic added 7 commits January 5, 2026 10:14

chore: first feedback round

054c6e6

Merge branch 'master' into leo/vaults

c31d1b1

Merge branch 'leo/vaults' of github.com:amforc/polkadot-sdk into leo/…

711b0b8

…vaults

feat: remove on_runtime_upgrade hook from the pallet

65030aa

chore: move the closing logic into the do_close_vault

8d87807

chore: fix typo

ff5479b

feat: initial bechmark helper implementation

f41e606

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Outdated Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Outdated Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Outdated Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Outdated Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Outdated Show resolved Hide resolved

kianenigma reviewed Jan 22, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Show resolved Hide resolved

Merge branch 'master' into leo/vaults

be3b6c9

This was referenced Feb 13, 2026

feat: upstream pallet-psm amforc/polkadot-sdk#3

Open

Introduce PSM pallet (part of the pUSD Project) #11068

Open

muharem reviewed Feb 23, 2026

View reviewed changes

muharem reviewed Feb 25, 2026

View reviewed changes

substrate/frame/vaults/src/lib.rs Outdated Show resolved Hide resolved

muharem reviewed Feb 25, 2026

View reviewed changes

substrate/frame/vaults/src/tests.rs Show resolved Hide resolved

muharem reviewed Feb 25, 2026

View reviewed changes

substrate/frame/vaults/src/benchmarking.rs Outdated Show resolved Hide resolved

Gioyik reviewed Feb 27, 2026

View reviewed changes

lrazovic added 11 commits March 9, 2026 10:14

chore: use ItemOf to represent the pUSD

3e56060

feat: let's be polite

2831917

feat: accrual interest only if unit

f1a9638

feat: heal the best effort

2d8e3ec

feat: heal extrinsic is now "free"

cdb14d6

feat: liquidate_vault "free" if successful

61fd9e7

feat: reduce CLA iff prinipal paid is not zero

3fe62bf

feat: liquidate_vault is now transactional

389590f

feat: track bad debt as principal + interest

7f9f3bd

test: add mcr raising test

e476d9b

bench: compute safe_mint_amount using MinimumMint

6d4abde

pgherveou added this to [preview] release tracker Mar 18, 2026

github-project-automation bot moved this to Todo in [preview] release tracker Mar 18, 2026

muharem reviewed Mar 19, 2026

View reviewed changes

pgherveou removed this from [preview] release tracker Mar 19, 2026

lrazovic added 7 commits March 19, 2026 20:03

chore: rename to Collateral and StableAsset

6cef850

bench: worst-case for mint and withdraw

755c773

feat: free heal only if successful

1868737

feat: store the PreviousStabilityFee

97d0989

chore: generate the weights

ae5aa00

Merge branch 'master' into leo/vaults

f9487d6

chore: move traits to frame_support

8f02ed4

		/// 365.25 days × 24 hours × 60 minutes × 60 seconds × 1000 milliseconds = 31,557,600,000
		const MILLIS_PER_YEAR: u64 = 31_557_600_000;

		vault.accrued_interest.saturating_accrue(accrued);
		vault.last_fee_update = now;


		Self::deposit_event(Event::BadDebtRepaid { amount: burned });

		Ok(())

Conversation

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

Uh oh!

Description

Integration

For Runtime Developers

For Pallet Developers

Review Notes

Key Features

Vault Lifecycle:

Hold Reasons:

Testing

Uh oh!

cla-bot-2021 bot commented Dec 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lrazovic Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lrazovic Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

muharem left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

muharem Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lrazovic Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lrazovic commented Dec 19, 2025 •

edited

Loading

lrazovic Jan 5, 2026 •

edited

Loading

lrazovic Jan 5, 2026 •

edited

Loading

muharem Mar 12, 2026 •

edited

Loading

lrazovic Mar 22, 2026 •

edited

Loading