feat: upstream pallet-psm

[lrazovic]

Description

This PR introduces pallet-psm, a new FRAME pallet that implements a Peg Stability Module (PSM) for pUSD. The pallet enables 1:1 swaps between pUSD and approved external stablecoins (e.g. USDC/USDT), with configurable mint/redeem fees and per-asset circuit breakers.

The pallet enforces a three-tier debt ceiling model before minting:

• System-wide cap from Vaults (MaximumIssuance)
• Aggregate PSM cap (MaxPsmDebtOfTotal)
• Per-asset normalized ceiling (AssetCeilingWeight)

It also adds cross-pallet interfaces in sp-pusd:

• VaultsInterface (PSM -> Vaults): query system issuance ceiling
• PsmInterface (Vaults/others -> PSM): query reserved PSM capacity

Integration

For Runtime Developers

To integrate pallet-psm into your runtime:

1. Add dependency to your runtime Cargo.toml:

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

2. Implement the Config trait in your runtime:

impl pallet_psm::Config for Runtime {
    type Asset = Assets;                         // fungibles impl for pUSD + external assets
    type AssetId = u32;                          // asset identifier type
    type VaultsInterface = Vaults;               // must implement sp_pusd::VaultsInterface
    type ManagerOrigin = EnsurePsmManager;       // returns PsmManagerLevel (Full/Emergency)
    type WeightInfo = pallet_psm::weights::SubstrateWeight<Runtime>;
    #[cfg(feature = "runtime-benchmarks")]
    type BenchmarkHelper = PsmBenchmarkHelper;
    type StablecoinAssetId = StablecoinAssetId;  // pUSD asset id
    type InsuranceFund = InsuranceFundAccount;   // fee recipient
    type PalletId = PsmPalletId;                 // PSM reserve account derivation
    type MinSwapAmount = MinSwapAmount;          // minimum mint/redeem amount
}

3. Add to construct_runtime!:

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

4. Ensure Vaults exposes issuance ceiling to PSM:

impl sp_pusd::VaultsInterface for Vaults {
    type Balance = Balance;
    fn get_maximum_issuance() -> Balance {
        // return system-wide pUSD ceiling
    }
}

5. For existing chains, include the migration:

pub struct PsmInitialConfig;

impl pallet_psm::migrations::v1::InitialPsmConfig<Runtime> for PsmInitialConfig {
    fn max_psm_debt_of_total() -> Permill { Permill::from_percent(10) }
    fn external_asset_ids() -> Vec<AssetId> { vec![USDC_ASSET_ID, USDT_ASSET_ID] }
    fn asset_configs() -> BTreeMap<AssetId, (Permill, Permill, Permill)> {
        // asset -> (mint_fee, redeem_fee, ceiling_weight)
        [
            (USDC_ASSET_ID, (Permill::from_percent(1), Permill::from_percent(1), Permill::from_percent(50))),
            (USDT_ASSET_ID, (Permill::from_percent(1), Permill::from_percent(1), Permill::from_percent(50))),
        ].into_iter().collect()
    }
}

pub type Migrations = (
    pallet_psm::migrations::v1::MigrateToV1<Runtime, PsmInitialConfig>,
);

For Pallet Developers

Other pallets can query PSM-reserved issuance capacity via PsmInterface:

use sp_pusd::PsmInterface;

let reserved = <Psm as PsmInterface>::reserved_capacity();

This can be used to account for PSM-reserved issuance when computing vault minting headroom.

Review Notes

Key Features

• 1:1 swaps: mint (external -> pUSD) and redeem (pUSD -> external)
• Multi-asset support with explicit approval list (add_external_asset / remove_external_asset)
• Three-tier debt ceiling enforcement (system-wide, aggregate PSM, per-asset normalized)
• Per-asset circuit breaker: AllEnabled -> MintingDisabled -> AllDisabled
• Tiered governance origin:
  • Full: all parameter and asset-management operations
  • Emergency: can only set circuit breaker status
• Fee model:
  • Mint fee: deducted from minted pUSD, fee minted to Insurance Fund
  • Redeem fee: deducted from output, fee transferred in pUSD to Insurance Fund
• Safety invariant on redeem: limited by tracked PsmDebt (not just raw reserve), preventing withdrawal of donated reserves
• Includes benchmarks and V0 -> V1 migration for post-genesis deployment

Swap Lifecycle

Mint (External -> pUSD):

1. User calls mint(asset_id, external_amount)
2. Checks: approved asset, circuit breaker, min amount
3. Enforces ceilings in order: system-wide -> aggregate PSM -> per-asset
4. Transfers external asset into PSM account
5. Mints pUSD to user minus fee
6. Mints fee amount as pUSD to Insurance Fund
7. Increases PsmDebt[asset_id]

Redeem (pUSD -> External):

1. User calls redeem(asset_id, pusd_amount)
2. Checks: approved asset, circuit breaker, min amount
3. Calculates fee and external output amount
4. Verifies tracked debt and reserve are sufficient
5. Burns pUSD principal portion from user
6. Transfers pUSD fee from user to Insurance Fund
7. Transfers external asset from PSM account to user
8. Decreases PsmDebt[asset_id]

Governance/Operations

• set_minting_fee
• set_redemption_fee
• set_max_psm_debt
• set_asset_ceiling_weight
• set_asset_status
• add_external_asset
• remove_external_asset (requires zero debt; cleans up config storage)

Testing

The pallet includes comprehensive coverage for:

• Mint/redeem success paths and failure modes
• Fee edge cases (0%, non-zero, 100%)
• Three-tier ceiling enforcement and boundary conditions
• Per-asset ceiling redistribution when weight is set to 0%
• Circuit breaker behavior per asset
• Full vs emergency governance permissions
• Asset onboarding/offboarding invariants and cleanup
• Reserve-vs-debt safety (donated reserve cannot be redeemed)
• Long-running mint/redeem cycles and accounting invariants
• Migration tests (v0 -> v1 and skip-when-already-v1)