Introduce Vaults pallet (part of the pUSD Project)

Cargo.toml

@@ -477,6 +477,7 @@ members = [
 	"substrate/frame/tx-pause",
 	"substrate/frame/uniques",
 	"substrate/frame/utility",
+	"substrate/frame/vaults",
 	"substrate/frame/verify-signature",
 	"substrate/frame/vesting",
 	"substrate/frame/whitelist",
@@ -1089,6 +1090,7 @@ pallet-treasury = { path = "substrate/frame/treasury", default-features = false
 pallet-tx-pause = { default-features = false, path = "substrate/frame/tx-pause" }
 pallet-uniques = { path = "substrate/frame/uniques", default-features = false }
 pallet-utility = { path = "substrate/frame/utility", default-features = false }
+pallet-vaults = { path = "substrate/frame/vaults", default-features = false }
 pallet-verify-signature = { path = "substrate/frame/verify-signature", default-features = false }
 pallet-vesting = { path = "substrate/frame/vesting", default-features = false }
 pallet-whitelist = { path = "substrate/frame/whitelist", default-features = false }

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

@@ -23,7 +23,7 @@ use crate::{
 	constants::currency::*, frame_support::build_struct_json_patch, AccountId, AssetsConfig,
 	BabeConfig, Balance, BalancesConfig, ElectionsConfig, NominationPoolsConfig, ReviveConfig,
 	RuntimeGenesisConfig, SessionConfig, SessionKeys, SocietyConfig, StakerStatus, StakingConfig,
-	SudoConfig, TechnicalCommitteeConfig, BABE_GENESIS_EPOCH_CONFIG,
+	SudoConfig, TechnicalCommitteeConfig, VaultsConfig, BABE_GENESIS_EPOCH_CONFIG,
 };
 use alloc::{vec, vec::Vec};
 use pallet_im_online::sr25519::AuthorityId as ImOnlineId;
@@ -98,6 +98,30 @@ pub fn kitchensink_genesis(
 		revive: ReviveConfig {
 			mapped_accounts: endowed_accounts.iter().filter(|x| ! is_eth_derived(x)).cloned().collect(),
 		},
+		vaults: VaultsConfig {
+			// 180% - Minimum safety margin before liquidation
+			minimum_collateralization_ratio: sp_runtime::FixedU128::from_rational(180, 100),
+			// 200% - Prevents immediate liquidation after minting
+			initial_collateralization_ratio: sp_runtime::FixedU128::from_rational(200, 100),
+			// 4% annual stability fee
+			stability_fee: sp_runtime::Permill::from_percent(4),
+			// 13% liquidation penalty
+			liquidation_penalty: sp_runtime::Permill::from_percent(13),
+			// 20M pUSD system-wide debt ceiling (6 decimals)
+			maximum_issuance: 20_000_000 * 1_000_000,
+			// 20M pUSD maximum concurrent liquidation exposure
+			max_liquidation_amount: 20_000_000 * 1_000_000,
+			// 10M pUSD maximum single vault debt
+			max_position_amount: 10_000_000 * 1_000_000,
+			// Minimum collateral deposit to create a vault: 100 DOT.
+			minimum_deposit: 100 * DOLLARS,
+			// Minimum mint amount: 5 pUSD.
+			minimum_mint: 5 * 1_000_000,
+			// 4 hours stale vault threshold (milliseconds)
+			stale_vault_threshold: 4 * 60 * 60 * 1000,
+			// 1 hour oracle staleness threshold (milliseconds)
+			oracle_staleness_threshold: 60 * 60 * 1000,
+		},
 	})
 }
 

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

@@ -32,7 +32,7 @@ use pallet_treasury::ArgumentsFactory as PalletTreasuryArgumentsFactory;
 #[cfg(feature = "runtime-benchmarks")]
 use polkadot_sdk::sp_core::crypto::FromEntropy;
 
-use polkadot_sdk::*;
+use polkadot_sdk::{cumulus_primitives_core::Location, *};
 
 use alloc::{vec, vec::Vec};
 use codec::{Decode, DecodeWithMemTracking, Encode, MaxEncodedLen};
@@ -2881,6 +2881,9 @@ mod runtime {
 	#[runtime::pallet_index(85)]
 	pub type Oracle = pallet_oracle::Pallet<Runtime>;
 
+	#[runtime::pallet_index(86)]
+	pub type Vaults = pallet_vaults::Pallet<Runtime>;
+
 	#[runtime::pallet_index(89)]
 	pub type MetaTx = pallet_meta_tx::Pallet<Runtime>;
 
@@ -3062,6 +3065,183 @@ impl pallet_oracle::Config for Runtime {
 	type BenchmarkHelper = OracleBenchmarkingHelper;
 }
 
+parameter_types! {
+	/// The pUSD stablecoin asset ID.
+	pub const VaultsStablecoinAssetId: u32 = 1;
+	/// DOT collateral location.
+	pub VaultsCollateralLocation: Location = Location::here();
+	/// Maximum vaults to process in on_idle per block.
+	pub const VaultsMaxOnIdleItems: u32 = 16;
+}
+
+type VaultsAsset = ItemOf<Assets, VaultsStablecoinAssetId, AccountId>;
+
+/// Insurance fund account that receives protocol revenue (interest and penalties).
+pub struct InsuranceFundAccount;
+impl frame_support::traits::Get<AccountId> for InsuranceFundAccount {
+	fn get() -> AccountId {
+		// Use a deterministic insurance fund account
+		sp_runtime::traits::AccountIdConversion::<AccountId>::into_account_truncating(
+			&frame_support::PalletId(*b"py/insur"),
+		)
+	}
+}
+
+/// Mock oracle adapter that provides a fixed price for now.
+///
+/// This adapter implements `ProvidePrice` with a hardcoded DOT price.
+/// For production, replace this with a real oracle integration.
+///
+/// **Price format (normalized):** smallest_pUSD_units / smallest_collateral_unit
+///
+/// Default DOT price: $4.21 normalized for DOT (10 decimals) and pUSD (6 decimals)
+/// Price = 4.21 * 10^6 / 10^10 = 0.000421
+/// As FixedU128: 421_000_000_000_000 (0.000421 * 10^18)
+pub const DEFAULT_DOT_PRICE: u128 = 421_000_000_000_000;
+
+#[cfg(feature = "runtime-benchmarks")]
+frame_support::parameter_types! {
+	/// Storage for benchmark price override.
+	/// When set, MockOracleAdapter will use this price instead of the default.
+	pub storage BenchmarkOraclePrice: Option<FixedU128> = None;
+}
+
+/// Example calculation for DOT at $4.21:
+/// - DOT has 10 decimals, pUSD has 6 decimals
+/// - 1 DOT = 4.21 pUSD
+/// - Normalized price = 4.21 × 10^6 / 10^10 = 0.000421
+/// - As FixedU128 (18 decimals): 0.000421 × 10^18 = 421_000_000_000_000
+pub struct MockOracleAdapter;
+impl pallet_vaults::ProvidePrice for MockOracleAdapter {
+	type Moment = u64;
+
+	fn get_price(asset: &Location) -> Option<(FixedU128, Self::Moment)> {
+		// Only support DOT (native asset) for now
+		if *asset != Location::here() {
+			return None;
+		}
+
+		// Check for benchmark price override
+		#[cfg(feature = "runtime-benchmarks")]
+		let price = BenchmarkOraclePrice::get().unwrap_or(FixedU128::from_inner(DEFAULT_DOT_PRICE));
+
+		#[cfg(not(feature = "runtime-benchmarks"))]
+		let price = FixedU128::from_inner(DEFAULT_DOT_PRICE);
+
+		// Use current timestamp from the Timestamp pallet
+		let now = <Timestamp as frame_support::traits::Time>::now();
+
+		Some((price, now))
+	}
+}
+
+/// Stub implementation for the Auctions handler.
+///
+/// This is a placeholder until a proper Auctions pallet is implemented.
+/// Currently, liquidations will fail with `Unimplemented` error.
+///
+/// TODO: Replace with actual pallet_auctions integration when available.
+pub struct AuctionAdapter;
+impl pallet_vaults::AuctionsHandler<AccountId, Balance> for AuctionAdapter {
+	fn start_auction(
+		_vault_owner: AccountId,
+		_collateral_amount: Balance,
+		_debt: frame_support::traits::DebtComponents<Balance>,
+		_keeper: AccountId,
+	) -> Result<u32, frame_support::pallet_prelude::DispatchError> {
+		// During benchmarks, return success to allow liquidation benchmarks to complete
+		#[cfg(feature = "runtime-benchmarks")]
+		return Ok(1);
+
+		// TODO: Implement actual auction logic when pallet_auctions is available
+		// For now, liquidations are disabled
+		#[cfg(not(feature = "runtime-benchmarks"))]
+		Err(frame_support::pallet_prelude::DispatchError::Other("Auctions not yet implemented"))
+	}
+}
+
+/// EnsureOrigin implementation for vaults management that supports privilege levels.
+///
+/// - Root origin → `VaultsManagerLevel::Full` (can modify all parameters)
+///
+/// TODO: In the future, this can be extended to support Emergency privilege level
+/// via a (new) specific governance origin that can only lower the debt ceiling.
+pub struct EnsureVaultsManager;
+impl frame_support::traits::EnsureOrigin<RuntimeOrigin> for EnsureVaultsManager {
+	type Success = pallet_vaults::VaultsManagerLevel;
+
+	fn try_origin(o: RuntimeOrigin) -> Result<Self::Success, RuntimeOrigin> {
+		use frame_system::RawOrigin;
+
+		match o.clone().into() {
+			Ok(RawOrigin::Root) => Ok(pallet_vaults::VaultsManagerLevel::Full),
+			_ => Err(o),
+		}
+	}
+
+	#[cfg(feature = "runtime-benchmarks")]
+	fn try_successful_origin() -> Result<RuntimeOrigin, ()> {
+		Ok(RuntimeOrigin::root())
+	}
+}
+
+/// Benchmark helper for the Vaults pallet.
+#[cfg(feature = "runtime-benchmarks")]
+pub struct VaultsBenchmarkHelper;
+
+#[cfg(feature = "runtime-benchmarks")]
+impl pallet_vaults::BenchmarkHelper for VaultsBenchmarkHelper {
+	fn create_stablecoin_asset() {
+		use frame_support::traits::fungibles::Create;
+
+		// Ensure the owner account exists
+		let owner = InsuranceFundAccount::get();
+		let _ = frame_system::Pallet::<Runtime>::inc_providers(&owner);
+
+		// Create the asset if it doesn't exist (ignore errors if already exists)
+		let _ = <Assets as Create<AccountId>>::create(
+			VaultsStablecoinAssetId::get(),
+			owner.clone(),
+			true, // is_sufficient
+			1,    // min_balance
+		);
+	}
+
+	fn advance_time(millis: u64) {
+		let current = pallet_timestamp::Now::<Runtime>::get();
+		let new_time = current.saturating_add(millis);
+		pallet_timestamp::Now::<Runtime>::put(new_time);
+	}
+
+	fn set_price(price: sp_runtime::FixedU128) {
+		BenchmarkOraclePrice::set(&Some(price));
+		log::info!(
+			target: "runtime::vaults::benchmark",
+			"set_price: {:?}",
+			price
+		);
+	}
+}
+
+/// Configure the Vaults pallet.
+impl pallet_vaults::Config for Runtime {
+	type Collateral = Balances;
+	type RuntimeHoldReason = RuntimeHoldReason;
+	type StableAsset = VaultsAsset;
+	type InsuranceFund = InsuranceFundAccount;
+	type FeeHandler = ResolveTo<TreasuryAccount, Balances>;
+	type SurplusHandler = ResolveTo<TreasuryAccount, VaultsAsset>;
+	type TimeProvider = Timestamp;
+	type ManagerOrigin = EnsureVaultsManager;
+	type MaxOnIdleItems = VaultsMaxOnIdleItems;
+	type Oracle = MockOracleAdapter;
+	type CollateralLocation = VaultsCollateralLocation;
+	type AuctionsHandler = AuctionAdapter;
+	type WeightInfo = pallet_vaults::weights::SubstrateWeight<Runtime>;
+	#[cfg(feature = "runtime-benchmarks")]
+	type BenchmarkHelper = VaultsBenchmarkHelper;
+}
+
 /// MMR helper types.
 mod mmr {
 	use super::*;
@@ -3200,6 +3380,7 @@ mod benches {
 		[pallet_nft_fractionalization, NftFractionalization]
 		[pallet_utility, Utility]
 		[pallet_vesting, Vesting]
+		[pallet_vaults, Vaults]
 		[pallet_whitelist, Whitelist]
 		[pallet_tx_pause, TxPause]
 		[pallet_safe_mode, SafeMode]

substrate/frame/support/src/traits.rs

@@ -28,8 +28,12 @@ pub use tokens::{
 	},
 	fungible, fungibles,
 	imbalance::{Imbalance, OnUnbalanced, SignedImbalance},
-	nonfungible, nonfungible_v2, nonfungibles, nonfungibles_v2, BalanceStatus,
-	ExistenceRequirement, Locker, WithdrawReasons,
+	nonfungible, nonfungible_v2, nonfungibles, nonfungibles_v2,
+	stable::{
+		AuctionsHandler, CollateralManager, DebtComponents, PaymentBreakdown, PsmInterface,
+		VaultsInterface,
+	},
+	BalanceStatus, ExistenceRequirement, Locker, WithdrawReasons,
 };
 
 mod members;

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

@@ -29,6 +29,7 @@ pub mod nonfungibles;
 pub mod nonfungibles_v2;
 pub use imbalance::Imbalance;
 pub mod pay;
+pub mod stable;
 pub mod transfer;
 pub use misc::{
 	AssetId, Balance, BalanceStatus, ConversionFromAssetBalance, ConversionToAssetBalance,