lib.rs

// KILT Blockchain – https://botlabs.org
// Copyright (C) 2019-2024 BOTLabs GmbH

// The KILT Blockchain is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.

// The KILT Blockchain is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.

// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

// If you feel like getting in touch with us, you can do so at info@botlabs.org

#![cfg_attr(not(feature = "std"), no_std)]

pub use pallet::*;

#[cfg(feature = "runtime-benchmarks")]
mod benchmarking;
#[cfg(any(test, feature = "runtime-benchmarks"))]
mod mock;
#[cfg(test)]
mod tests;
#[cfg(any(feature = "try-runtime", test))]
mod try_state;

pub mod curves;
mod default_weights;
pub mod traits;
mod types;
#[cfg(feature = "runtime-benchmarks")]
pub use benchmarking::BenchmarkHelper;

pub use types::{PoolDetails, Round};

pub use default_weights::WeightInfo;

#[frame_support::pallet]
// `.expect()` is used in the macro-generated code, and we have to ignore it.
#[allow(clippy::expect_used)]
// `unreachable` is used in the macro-generated code, and we have to ignore it.
#[allow(clippy::unreachable)]
// `ref` keyword is used in the macro-generated code, and we have to ignore it.
#[allow(clippy::ref_patterns)]
// The `pallet::event` macro shadows the `deposit_event` definition of `frame_system::Config`.
// This means we cannot avoid shadow reuses anymore, and for new pallets this `allow` clause should only be added at the
// very end of the development cycle of a pallet, and from time to time it should be commented out to catch any issues
// other than the one generated by the `pallet::event` macro.
#[allow(clippy::shadow_reuse)]
pub mod pallet {

	use frame_support::{
		dispatch::DispatchResult,
		pallet_prelude::*,
		traits::{
			fungible::{Inspect as InspectFungible, MutateHold},
			fungibles::{
				metadata::{Inspect as InspectMetadata, Mutate as MutateMetadata},
				Create as CreateFungibles, Destroy as DestroyFungibles, Inspect as InspectFungibles,
				Mutate as MutateFungibles,
			},
			tokens::{DepositConsequence, Fortitude, Precision as WithdrawalPrecision, Preservation, Provenance},
			AccountTouch,
		},
		Hashable, Parameter,
	};
	use frame_system::pallet_prelude::*;
	use sp_arithmetic::ArithmeticError;
	use sp_core::U256;
	use sp_runtime::{
		traits::{
			Bounded, CheckedConversion, SaturatedConversion, Saturating, StaticLookup, UniqueSaturatedInto, Zero,
		},
		BoundedVec, DispatchError, TokenError,
	};
	use sp_std::{
		collections::btree_set::BTreeSet,
		iter::Iterator,
		ops::{AddAssign, BitOrAssign, ShlAssign},
		prelude::*,
		vec::Vec,
	};
	use substrate_fixed::{
		traits::{Fixed, FixedSigned, FixedUnsigned, ToFixed},
		types::I9F23,
	};

	use crate::{
		curves::{balance_to_fixed, fixed_to_balance, BondingFunction, Curve, CurveInput},
		traits::{FreezeAccounts, NextAssetIds, ResetTeam},
		types::{Locks, PoolDetails, PoolManagingTeam, PoolStatus, Round, TokenMeta},
		WeightInfo,
	};

	pub(crate) type AccountIdLookupOf<T> =
		<<T as frame_system::Config>::Lookup as sp_runtime::traits::StaticLookup>::Source;

	pub(crate) type AccountIdOf<T> = <T as frame_system::Config>::AccountId;

	pub(crate) type DepositBalanceOf<T> =
		<<T as Config>::DepositCurrency as InspectFungible<<T as frame_system::Config>::AccountId>>::Balance;

	pub(crate) type CollateralBalanceOf<T> =
		<<T as Config>::Collaterals as InspectFungibles<<T as frame_system::Config>::AccountId>>::Balance;

	pub(crate) type FungiblesBalanceOf<T> =
		<<T as Config>::Fungibles as InspectFungibles<<T as frame_system::Config>::AccountId>>::Balance;

	pub type FungiblesAssetIdOf<T> =
		<<T as Config>::Fungibles as InspectFungibles<<T as frame_system::Config>::AccountId>>::AssetId;

	pub type CollateralAssetIdOf<T> =
		<<T as Config>::Collaterals as InspectFungibles<<T as frame_system::Config>::AccountId>>::AssetId;

	pub(crate) type BoundedCurrencyVec<T> = BoundedVec<FungiblesAssetIdOf<T>, <T as Config>::MaxCurrenciesPerPool>;

	pub(crate) type StringInputOf<T> = BoundedVec<u8, <T as Config>::MaxStringInputLength>;

	pub(crate) type CurveParameterTypeOf<T> = <T as Config>::CurveParameterType;

	pub(crate) type CurveParameterInputOf<T> = <T as Config>::CurveParameterInput;

	pub type PoolDetailsOf<T> = PoolDetails<
		<T as frame_system::Config>::AccountId,
		Curve<CurveParameterTypeOf<T>>,
		BoundedCurrencyVec<T>,
		CollateralAssetIdOf<T>,
		DepositBalanceOf<T>,
	>;

	/// Minimum required amount of integer and fractional bits to perform ln,
	/// sqrt, and exp operations
	pub(crate) type Precision = I9F23;

	/// Type used for the passive supply of a pool
	pub(crate) type PassiveSupply<T> = Vec<T>;

	pub(crate) type TokenMetaOf<T> = TokenMeta<FungiblesBalanceOf<T>, StringInputOf<T>, StringInputOf<T>>;

	pub(crate) const LOG_TARGET: &str = "runtime::pallet-bonded-coins";

	/// Configure the pallet by specifying the parameters and types on which it
	/// depends.
	#[pallet::config]
	pub trait Config: frame_system::Config {
		/// Because this pallet emits events, it depends on the runtime's
		/// definition of an event.
		type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
		/// The currency used for storage deposits.
		type DepositCurrency: MutateHold<Self::AccountId, Reason = Self::RuntimeHoldReason>;
		/// A fungibles trait implementation to interact with currencies which
		/// can be used as collateral for minting bonded tokens.
		type Collaterals: MutateFungibles<Self::AccountId>
			+ AccountTouch<CollateralAssetIdOf<Self>, Self::AccountId>
			+ InspectMetadata<Self::AccountId>;

		/// Implementation of creating and managing new fungibles
		type Fungibles: CreateFungibles<Self::AccountId>
			+ DestroyFungibles<Self::AccountId>
			+ MutateMetadata<Self::AccountId>
			+ InspectMetadata<Self::AccountId>
			+ MutateFungibles<Self::AccountId>
			+ FreezeAccounts<Self::AccountId, FungiblesAssetIdOf<Self>>
			+ ResetTeam<Self::AccountId>;
		/// The maximum number of currencies allowed for a single pool.
		#[pallet::constant]
		type MaxCurrenciesPerPool: Get<u32>;

		#[pallet::constant]
		type MaxStringInputLength: Get<u32>;

		/// The maximum denomination that bonded currencies can use. This should
		/// be configured so that
		/// 10^MaxDenomination < 2^CurveParameterType::frac_nbits()
		/// as larger denominations could result in truncation.
		#[pallet::constant]
		type MaxDenomination: Get<u8>;

		/// The deposit required for each bonded currency.
		#[pallet::constant]
		type DepositPerCurrency: Get<DepositBalanceOf<Self>>;

		/// The base deposit required to create a new pool.
		#[pallet::constant]
		type BaseDeposit: Get<DepositBalanceOf<Self>>;

		/// The origin for most permissionless and priviledged operations.
		type DefaultOrigin: EnsureOrigin<Self::RuntimeOrigin, Success = Self::AccountId>;
		/// The dedicated origin for creating new bonded currency pools
		/// (typically permissionless).
		type PoolCreateOrigin: EnsureOrigin<Self::RuntimeOrigin, Success = Self::AccountId>;
		/// The origin for permissioned operations (force_* transactions).
		type ForceOrigin: EnsureOrigin<Self::RuntimeOrigin>;
		/// The type used for pool ids
		type PoolId: Parameter + MaxEncodedLen + From<[u8; 32]> + Into<Self::AccountId>;

		type RuntimeHoldReason: From<Self::HoldReason>;
		type HoldReason: TryFrom<Self::PoolId>;

		/// The type used for the curve parameters. This is the type used in the
		/// calculation steps and stored in the pool details.
		type CurveParameterType: Parameter
			+ Member
			+ FixedSigned
			+ MaxEncodedLen
			+ PartialOrd<Precision>
			+ From<Precision>;

		/// Input type for curve parameters. This is the type used in the
		/// extrinsic calls to create a new pool. It is converted to
		/// `CurveParameterType`.
		type CurveParameterInput: Parameter + FixedUnsigned + MaxEncodedLen;

		type WeightInfo: WeightInfo;

		type NextAssetIds: NextAssetIds<Self>;

		/// Benchmark helper to calculate asset ids for the collateral and
		/// bonded currencies.
		#[cfg(feature = "runtime-benchmarks")]
		type BenchmarkHelper: crate::benchmarking::BenchmarkHelper<Self>;
	}

	#[pallet::pallet]
	pub struct Pallet<T>(_);

	#[pallet::hooks]
	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
		fn integrity_test() {
			let scaling_factor = U256::from(10u8).checked_pow(T::MaxDenomination::get().into()).expect(
				"`MaxDenomination` is set so high that the resulting scaling factor cannot be represented. /
				Any attempt to mint or burn on a pool where `10^denomination > 2^256` _WILL_ fail.",
			);

			assert!(
				U256::from(2u8).pow(T::CurveParameterType::frac_nbits().into()) > scaling_factor,
				"In order to prevent truncation of balances, `MaxDenomination` should be configured such \
				that the maximum scaling factor `10^MaxDenomination` is smaller than the fractional \
				capacity `2^frac_nbits` of `CurveParameterType`",
			);
		}

		#[cfg(feature = "try-runtime")]
		fn try_state(_n: BlockNumberFor<T>) -> Result<(), sp_runtime::TryRuntimeError> {
			crate::try_state::do_try_state::<T>()
		}
	}

	#[pallet::storage]
	#[pallet::getter(fn pool_with_id)]
	pub type Pools<T: Config> = StorageMap<_, Twox64Concat, T::PoolId, PoolDetailsOf<T>, OptionQuery>;

	#[pallet::event]
	#[pallet::generate_deposit(pub(super) fn deposit_event)]
	pub enum Event<T: Config> {
		/// Locks on a pool have been added or removed.
		LockSet { id: T::PoolId, lock: Locks },
		/// All locks on this pool have been cleared.
		Unlocked { id: T::PoolId },
		/// A new bonded token pool has been created.
		PoolCreated { id: T::PoolId },
		/// A bonded token pool has been moved to refunding state.
		RefundingStarted { id: T::PoolId },
		/// A bonded token pool has been moved to destroying state.
		DestructionStarted { id: T::PoolId },
		/// Collateral distribution to bonded token holders has been completed
		/// for this pool (no more tokens or no more collateral to distribute).
		RefundComplete { id: T::PoolId },
		/// A bonded token pool has been fully destroyed and all collateral and
		/// deposits have been refunded.
		Destroyed { id: T::PoolId },
		/// The manager of a pool has been updated.
		ManagerUpdated {
			id: T::PoolId,
			manager: Option<T::AccountId>,
		},
		/// The asset managing team of a pool has been reset.
		TeamChanged {
			id: T::PoolId,
			team: PoolManagingTeam<T::AccountId>,
		},
	}

	#[pallet::error]
	pub enum Error<T> {
		/// The pool id is not currently registered.
		PoolUnknown,
		/// The pool has no associated bonded currency with the given index.
		IndexOutOfBounds,
		/// The pool does not hold collateral to be refunded, or has no
		/// remaining supply of tokens to exchange. Call start_destroy to
		/// intiate teardown.
		NothingToRefund,
		/// The user is not privileged to perform the requested operation.
		NoPermission,
		/// The pool is deactivated (i.e., in destroying or refunding state) and
		/// not available for use.
		PoolNotLive,
		/// There are active accounts associated with this pool and thus it
		/// cannot be destroyed at this point.
		LivePool,
		/// This operation can only be made when the pool is in refunding state.
		NotRefunding,
		/// The number of currencies linked to a pool exceeds the limit
		/// parameter. Thrown by transactions that require specifying the number
		/// of a pool's currencies in order to determine weight limits upfront.
		CurrencyCount,
		/// Raised if pool creation arguments are outside of the allowed value
		/// range.
		InvalidInput,
		/// An internal error occurred. This should never happen.
		Internal,
		/// The collateral required for the minting operation exceeds the
		/// provided maximum cost or the released collateral in the burning
		/// operation is less than the minimum return.
		Slippage,
		/// The calculated collateral is zero.
		ZeroCollateral,
		/// A pool has to contain at least one bonded currency.
		ZeroBondedCurrency,
	}

	#[pallet::call]
	impl<T: Config> Pallet<T>
	where
		<CurveParameterTypeOf<T> as Fixed>::Bits:
			Copy + ToFixed + AddAssign + BitOrAssign + ShlAssign + TryFrom<U256> + TryInto<U256>,
		CollateralBalanceOf<T>: Into<U256> + TryFrom<U256>,
		FungiblesBalanceOf<T>: Into<U256> + TryFrom<U256>,
	{
		/// Creates a new bonded token pool. The pool will be created with the
		/// given curve, collateral currency, and bonded currencies. The pool
		/// will be owned by the origin account.
		///
		/// # Parameters
		/// - `origin`: The origin of the call.
		/// - `curve`: The curve parameters for the pool.
		/// - `collateral_id`: The ID of the collateral currency.
		/// - `currencies`: A bounded vector of token metadata for the bonded
		///   currencies. Note that no two currencies may use the same name or
		///   symbol.
		/// - `denomination`: The denomination for the bonded currencies.
		/// - `transferable`: A boolean indicating if the bonded currencies are
		///   transferable.
		///
		/// # Returns
		/// - `DispatchResult`: The result of the dispatch.
		///
		/// # Errors
		/// - `Error::<T>::InvalidInput`: If either
		///   - the denomination is greater than the maximum allowed
		///   - the curve input is invalid
		///   - two currencies use the same name or symbol
		/// - `Error::<T>::Internal`: If the conversion to `BoundedVec` fails.
		/// - Other errors depending on the types in the config.
		#[pallet::call_index(0)]
		#[pallet::weight({
			let currency_length = currencies.len().saturated_into();
			match curve {
				CurveInput::Polynomial(_) => T::WeightInfo::create_pool_polynomial(currency_length),
				CurveInput::SquareRoot(_) => T::WeightInfo::create_pool_square_root(currency_length),
				CurveInput::Lmsr(_) => T::WeightInfo::create_pool_lmsr(currency_length),
			}
		})]
		pub fn create_pool(
			origin: OriginFor<T>,
			curve: CurveInput<CurveParameterInputOf<T>>,
			collateral_id: CollateralAssetIdOf<T>,
			currencies: BoundedVec<TokenMetaOf<T>, T::MaxCurrenciesPerPool>,
			denomination: u8,
			transferable: bool,
			min_operation_balance: u128,
		) -> DispatchResult {
			let who = T::PoolCreateOrigin::ensure_origin(origin)?;

			ensure!(denomination <= T::MaxDenomination::get(), Error::<T>::InvalidInput);
			let checked_curve = curve.try_into().map_err(|_| Error::<T>::InvalidInput)?;

			let currency_length = currencies.len();
			ensure!(!currency_length.is_zero(), Error::<T>::ZeroBondedCurrency);

			let currency_ids = T::NextAssetIds::try_get(currency_length.saturated_into())
				.map_err(|e| e.into())
				.and_then(|ids| -> Result<BoundedCurrencyVec<T>, DispatchError> {
					if ids.len() != currency_length {
						log::error!(target: LOG_TARGET, "NextAssetIds::try_get returned wrong number of ids");
						return Err(Error::<T>::Internal.into());
					}
					BoundedCurrencyVec::<T>::try_from(ids).map_err(|_| {
						log::error!(target: LOG_TARGET, "Creating boundedVec from ids failed");
						Error::<T>::Internal.into()
					})
				})?;

			let pool_id = T::PoolId::from(currency_ids.blake2_256());

			if Pools::<T>::contains_key(&pool_id) {
				log::error!(target: LOG_TARGET, "Attempt to create pool with pre-existing id {:?}", pool_id);
				return Err(Error::<T>::Internal.into());
			};

			let deposit_amount = Self::calculate_pool_deposit(currency_length);

			let hold_reason = Self::calculate_hold_reason(&pool_id)?;
			T::DepositCurrency::hold(&hold_reason, &who, deposit_amount)?;

			let pool_account = &pool_id.clone().into();

			// Touch the pool account in order to be able to transfer the collateral
			// currency to it. This should also verify that the currency actually exists.
			T::Collaterals::touch(collateral_id.clone(), pool_account, &who)?;

			// Enforce unique names and symbols by recording seen values in a set
			let mut names_seen = BTreeSet::<StringInputOf<T>>::new();
			let mut symbols_seen = BTreeSet::<StringInputOf<T>>::new();

			currencies.into_iter().zip(currency_ids.iter()).try_for_each(
				|(token_metadata, asset_id)| -> DispatchResult {
					let TokenMeta {
						min_balance,
						name,
						symbol,
					} = token_metadata;

					// insert() returns true if the set did not contain the inserted value
					let name_ok = name.is_empty() || names_seen.insert(name.clone());
					let symbol_ok = symbol.is_empty() || symbols_seen.insert(symbol.clone());
					ensure!(name_ok && symbol_ok, Error::<T>::InvalidInput);

					T::Fungibles::create(asset_id.clone(), pool_account.to_owned(), false, min_balance)?;

					// set metadata for new asset class
					T::Fungibles::set(
						asset_id.to_owned(),
						pool_account,
						name.into_inner(),
						symbol.into_inner(),
						denomination,
					)?;

					Ok(())
				},
			)?;

			Pools::<T>::set(
				&pool_id,
				Some(PoolDetails::new(
					who,
					checked_curve,
					collateral_id,
					currency_ids,
					transferable,
					denomination,
					min_operation_balance,
					deposit_amount,
				)),
			);

			Self::deposit_event(Event::PoolCreated { id: pool_id });

			Ok(())
		}

		/// Changes the managing team of all bonded currencies issued by this
		/// pool, setting it to the provided `team`. The origin account must be
		/// a manager of the pool.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring the caller to be a
		///   manager of the pool.
		/// - `pool_id`: The identifier of the pool.
		/// - `team`: The new managing team.
		/// - `currency_count`: The number of bonded currencies vector linked to
		///   the pool. Required for weight estimations.
		///
		/// # Returns
		/// - `DispatchResult`: The result of the dispatch.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::NoPermission`: If the caller is not a manager of the
		///   pool.
		/// - `Error::<T>::CurrencyCount`: If the actual number of currencies in
		///   the pool is larger than `currency_count`.
		/// - Other errors depending on the types in the config.
		#[pallet::call_index(1)]
		#[pallet::weight(T::WeightInfo::reset_team())]
		pub fn reset_team(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			team: PoolManagingTeam<AccountIdOf<T>>,
			currency_count: u32,
		) -> DispatchResult {
			let who = T::DefaultOrigin::ensure_origin(origin)?;

			let pool_details = Pools::<T>::get(&pool_id).ok_or(Error::<T>::PoolUnknown)?;

			let number_of_currencies = Self::get_currencies_number(&pool_details);
			ensure!(number_of_currencies <= currency_count, Error::<T>::CurrencyCount);

			ensure!(pool_details.is_manager(&who), Error::<T>::NoPermission);
			ensure!(pool_details.state.is_live(), Error::<T>::PoolNotLive);

			let pool_id_account = pool_id.clone().into();

			let PoolManagingTeam { ref freezer, ref admin } = team;

			pool_details.bonded_currencies.into_iter().try_for_each(|asset_id| {
				T::Fungibles::reset_team(
					asset_id,
					pool_id_account.clone(),
					admin.clone(),
					pool_id_account.clone(),
					freezer.clone(),
				)
			})?;

			Self::deposit_event(Event::TeamChanged { id: pool_id, team });

			Ok(())
		}

		/// Resets the manager of a pool. The new manager will be set to the
		/// provided account. If the new manager is `None`, the pool manager
		/// will be cleared, after which no further privileged changes to the
		/// pool can be made.
		/// The origin account must be a manager of the pool.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring the caller to be a
		///   manager of the pool.
		/// - `pool_id`: The identifier of the pool.
		/// - `new_manager`: The new manager account. If `None`, the pool will
		///   be set to permissionless.
		///
		/// # Returns
		/// - `DispatchResult`: The result of the dispatch.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::NoPermission`: If the caller is not a manager of the
		///   pool.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in active or locked
		///   state.
		#[pallet::call_index(2)]
		#[pallet::weight(T::WeightInfo::reset_manager())]
		pub fn reset_manager(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			new_manager: Option<AccountIdOf<T>>,
		) -> DispatchResult {
			let who = T::DefaultOrigin::ensure_origin(origin)?;
			Pools::<T>::try_mutate(&pool_id, |maybe_entry| -> DispatchResult {
				let entry = maybe_entry.as_mut().ok_or(Error::<T>::PoolUnknown)?;
				ensure!(entry.state.is_live(), Error::<T>::PoolNotLive);
				ensure!(entry.is_manager(&who), Error::<T>::NoPermission);
				entry.manager = new_manager.clone();

				Ok(())
			})?;

			Self::deposit_event(Event::ManagerUpdated {
				id: pool_id,
				manager: new_manager,
			});

			Ok(())
		}

		/// Locks a pool. The pool will be set to a locked state with the given
		/// locks. The origin account must be a manager of the pool.
		/// The pool must be in a locked or active state.
		/// The pool will be locked until the locks are removed.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring the caller to be a
		///   manager of the pool.
		/// - `pool_id`: The identifier of the pool to be locked.
		/// - `lock`: The locks to be applied to the pool. At least one lock
		///   flag must be set to `false` for a valid lock.
		///
		/// # Returns
		/// - `DispatchResult`: The result of the dispatch.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::NoPermission`: If the caller is not a manager of the
		///   pool.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live (locked or
		///   active) state.
		/// - `Error::<T>::InvalidInput`: If all lock flags are `true` (all
		///   operations enabled), which would be equivalent to an unlocked
		///   (active) pool state.
		#[pallet::call_index(3)]
		#[pallet::weight(T::WeightInfo::set_lock())]
		pub fn set_lock(origin: OriginFor<T>, pool_id: T::PoolId, lock: Locks) -> DispatchResult {
			let who = T::DefaultOrigin::ensure_origin(origin)?;

			ensure!(lock.any_lock_set(), Error::<T>::InvalidInput);

			Pools::<T>::try_mutate(&pool_id, |pool| -> DispatchResult {
				let entry = pool.as_mut().ok_or(Error::<T>::PoolUnknown)?;
				ensure!(entry.state.is_live(), Error::<T>::PoolNotLive);
				ensure!(entry.is_manager(&who), Error::<T>::NoPermission);

				entry.state = PoolStatus::Locked(lock.clone());

				Ok(())
			})?;

			Self::deposit_event(Event::LockSet { id: pool_id, lock });

			Ok(())
		}

		/// Unlocks a pool. The pool will be set to an active state. The origin
		/// account must be a manager of the pool.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring the caller to be a
		///   manager of the pool.
		/// - `pool_id`: The identifier of the pool to be unlocked.
		///
		/// # Returns
		/// - `DispatchResult`: The result of the dispatch.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::NoPermission`: If the caller is not a manager of the
		///   pool.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live state.
		#[pallet::call_index(4)]
		#[pallet::weight(T::WeightInfo::unlock())]
		pub fn unlock(origin: OriginFor<T>, pool_id: T::PoolId) -> DispatchResult {
			let who = T::DefaultOrigin::ensure_origin(origin)?;

			Pools::<T>::try_mutate(&pool_id, |pool| -> DispatchResult {
				let entry = pool.as_mut().ok_or(Error::<T>::PoolUnknown)?;
				ensure!(entry.state.is_live(), Error::<T>::PoolNotLive);
				ensure!(entry.is_manager(&who), Error::<T>::NoPermission);

				entry.state = PoolStatus::Active;

				Ok(())
			})?;

			Self::deposit_event(Event::Unlocked { id: pool_id });

			Ok(())
		}

		/// Mints new bonded tokens. The tokens will be minted into the
		/// beneficiary account. In exchange, an amount of collateral determined
		/// by the pool's bonding curve is debited from the caller and
		/// transferred to the pool account.
		/// The origin account must be a manager of the pool if its state is
		/// `Locked` and `allow_mint` is false. The pool must be in a live
		/// (non-refunding, non-destroying) state.
		///
		/// # Parameters
		/// - `origin`: The origin of the call.
		/// - `pool_id`: The identifier of the pool.
		/// - `currency_idx`: The index of the currency in the bonded currencies
		///   vector.
		/// - `beneficiary`: The account to receive the minted tokens.
		/// - `amount_to_mint`: The amount of bonded tokens to mint.
		/// - `max_cost`: The maximum cost of collateral.
		/// - `currency_count`: The maximum number of currencies allowed in the
		///   pool.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::NoPermission`: If the caller does not have permission
		///   to mint.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `currency_count`.
		/// - `Error::<T>::IndexOutOfBounds`: If the currency index is out of
		///   bounds.
		/// - `ArithmeticError::Overflow`: If there is an overflow during the
		///   calculation.
		/// - `Error::<T>::Slippage`: If the cost exceeds `max_cost`.
		#[pallet::call_index(5)]
		#[pallet::weight({
			let weight_polynomial = T::WeightInfo::mint_into_polynomial(currency_count.to_owned());
			let weight_square_root = T::WeightInfo::mint_into_square_root(currency_count.to_owned());
			let weight_lmsr = T::WeightInfo::mint_into_lmsr(currency_count.to_owned());
			weight_polynomial.max(weight_square_root).max(weight_lmsr)
		})]
		pub fn mint_into(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			currency_idx: u32,
			beneficiary: AccountIdLookupOf<T>,
			amount_to_mint: FungiblesBalanceOf<T>,
			max_cost: CollateralBalanceOf<T>,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			let who = T::DefaultOrigin::ensure_origin(origin)?;
			let beneficiary = T::Lookup::lookup(beneficiary)?;

			let pool_details = Pools::<T>::get(&pool_id).ok_or(Error::<T>::PoolUnknown)?;

			let number_of_currencies = Self::get_currencies_number(&pool_details);
			ensure!(number_of_currencies <= currency_count, Error::<T>::CurrencyCount);

			ensure!(
				amount_to_mint >= pool_details.min_operation_balance.saturated_into(),
				TokenError::BelowMinimum
			);

			ensure!(pool_details.state.is_live(), Error::<T>::PoolNotLive);

			ensure!(pool_details.can_mint(&who), Error::<T>::NoPermission);

			let bonded_currencies = pool_details.bonded_currencies;

			let currency_idx: usize = currency_idx.saturated_into();

			let target_currency_id = bonded_currencies
				.get(currency_idx)
				.ok_or(Error::<T>::IndexOutOfBounds)?;

			let round_kind = Round::Up;

			let (active_pre, passive) = Self::calculate_normalized_passive_issuance(
				&bonded_currencies,
				pool_details.denomination,
				currency_idx,
				round_kind,
			)?;

			let normalized_amount_to_mint = balance_to_fixed(
				amount_to_mint.saturated_into::<u128>(),
				pool_details.denomination,
				round_kind,
			)?;

			let active_post = active_pre
				.checked_add(normalized_amount_to_mint)
				.ok_or(ArithmeticError::Overflow)?;

			let cost = Self::calculate_collateral(
				active_pre,
				active_post,
				passive,
				&pool_details.curve,
				pool_details.collateral.clone(),
				round_kind,
			)?;

			ensure!(cost > Zero::zero(), Error::<T>::ZeroCollateral);
			// fail if cost > max_cost
			ensure!(cost <= max_cost, Error::<T>::Slippage);

			// Transfer the collateral. We do not want to kill the minter, so this operation
			// can fail if the account is being reaped.
			T::Collaterals::transfer(
				pool_details.collateral,
				&who,
				&pool_id.into(),
				cost,
				Preservation::Preserve,
			)?;

			T::Fungibles::mint_into(target_currency_id.clone(), &beneficiary, amount_to_mint)?;

			if !pool_details.transferable {
				T::Fungibles::freeze(target_currency_id, &beneficiary).map_err(|freeze_error| {
					log::info!(target: LOG_TARGET, "Failed to freeze account: {:?}", freeze_error);
					freeze_error.into()
				})?;
			}

			Ok(Some(match pool_details.curve {
				Curve::Polynomial(_) => T::WeightInfo::mint_into_polynomial(number_of_currencies),
				Curve::SquareRoot(_) => T::WeightInfo::mint_into_square_root(number_of_currencies),
				Curve::Lmsr(_) => T::WeightInfo::mint_into_lmsr(number_of_currencies),
			})
			.into())
		}

		/// Burns a specified amount of bonded tokens from the callers account
		/// and transfers the corresponding collateral to the beneficiary.
		/// The amount of collateral to be transferred is calculated based on
		/// the amount of bonded tokens burned.
		///
		/// # Parameters
		/// - `origin`: The origin of the call.
		/// - `pool_id`: The identifier of the pool.
		/// - `currency_idx`: The index of the currency in the bonded currencies
		///   vector.
		/// - `beneficiary`: The account to receive the collateral.
		/// - `amount_to_burn`: The amount of bonded tokens to burn.
		/// - `min_return`: The minimum amount of collateral to return.
		/// - `currency_count`: The currency count in the pool, required for
		///   weight calculation.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::NoPermission`: If the caller does not have permission
		///   to burn.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `currency_count`.
		/// - `Error::<T>::IndexOutOfBounds`: If the currency index is out of
		///   bounds.
		/// - `ArithmeticError`: If there is an error during the calculation or
		///   while converting the amount to fixed types.
		/// - `Error::<T>::Slippage`: If the collateral return is less than
		///   `min_return`.
		#[pallet::call_index(6)]
		#[pallet::weight({
			let weight_polynomial = T::WeightInfo::burn_into_polynomial(currency_count.to_owned());
			let weight_square_root = T::WeightInfo::burn_into_square_root(currency_count.to_owned());
			let weight_lmsr = T::WeightInfo::burn_into_lmsr(currency_count.to_owned());
			weight_polynomial.max(weight_square_root).max(weight_lmsr)
		})]
		pub fn burn_into(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			currency_idx: u32,
			beneficiary: AccountIdLookupOf<T>,
			amount_to_burn: FungiblesBalanceOf<T>,
			min_return: CollateralBalanceOf<T>,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			let who = T::DefaultOrigin::ensure_origin(origin)?;
			let beneficiary = T::Lookup::lookup(beneficiary)?;

			let pool_details = Pools::<T>::get(&pool_id).ok_or(Error::<T>::PoolUnknown)?;

			ensure!(
				amount_to_burn >= pool_details.min_operation_balance.saturated_into(),
				TokenError::BelowMinimum
			);

			let number_of_currencies = Self::get_currencies_number(&pool_details);
			ensure!(number_of_currencies <= currency_count, Error::<T>::CurrencyCount);

			ensure!(pool_details.state.is_live(), Error::<T>::PoolNotLive);
			ensure!(pool_details.can_burn(&who), Error::<T>::NoPermission);

			let bonded_currencies = pool_details.bonded_currencies;

			let currency_idx: usize = currency_idx.saturated_into();
			let round_kind = Round::Down;

			let target_currency_id = bonded_currencies
				.get(currency_idx)
				.ok_or(Error::<T>::IndexOutOfBounds)?;

			let (high, passive) = Self::calculate_normalized_passive_issuance(
				&bonded_currencies,
				pool_details.denomination,
				currency_idx,
				round_kind,
			)?;

			let normalized_amount_to_burn = balance_to_fixed(amount_to_burn, pool_details.denomination, round_kind)?;

			let low = high
				.checked_sub(normalized_amount_to_burn)
				.ok_or(ArithmeticError::Underflow)?;

			let collateral_return = Self::calculate_collateral(
				low,
				high,
				passive,
				&pool_details.curve,
				pool_details.collateral.clone(),
				round_kind,
			)?;

			ensure!(collateral_return > Zero::zero(), Error::<T>::ZeroCollateral);
			ensure!(collateral_return >= min_return, Error::<T>::Slippage);

			// Transfer the collateral to the beneficiary.
			T::Collaterals::transfer(
				pool_details.collateral,
				&pool_id.into(),
				&beneficiary,
				collateral_return,
				Preservation::Expendable,
			)?;

			// just remove any locks, if existing.
			T::Fungibles::thaw(target_currency_id, &who).map_err(|freeze_error| {
				log::info!(target: LOG_TARGET, "Failed to thaw account: {:?}", freeze_error);
				// The thaw operation is failing, if there is no account to thaw. Overwrite the
				// error with FungiblesError::FundsUnavailable
				DispatchError::from(TokenError::FundsUnavailable)
			})?;

			// Burn the tokens from caller.
			T::Fungibles::burn_from(
				target_currency_id.clone(),
				&who,
				amount_to_burn,
				WithdrawalPrecision::Exact,
				Fortitude::Force,
			)?;

			let account_exists = T::Fungibles::total_balance(target_currency_id.clone(), &who) > Zero::zero();

			if !pool_details.transferable && account_exists {
				// Restore locks.
				T::Fungibles::freeze(target_currency_id, &who).map_err(|freeze_error| {
					log::info!(target: LOG_TARGET, "Failed to freeze account: {:?}", freeze_error);
					freeze_error.into()
				})?;
			}

			Ok(Some(match pool_details.curve {
				Curve::Polynomial(_) => T::WeightInfo::burn_into_polynomial(number_of_currencies),
				Curve::SquareRoot(_) => T::WeightInfo::burn_into_square_root(number_of_currencies),
				Curve::Lmsr(_) => T::WeightInfo::burn_into_lmsr(number_of_currencies),
			})
			.into())
		}

		/// Starts the refund process for a pool. The pool will be set to a
		/// refunding state. The origin account must be a manager of the pool.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring the caller to be a
		///   manager of the pool.
		/// - `pool_id`: The identifier of the pool to start the refund process
		///   for.
		/// - `currency_count`: The currency count in the pool, required for
		///   weight calculation.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `max_currencies`.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live state.
		/// - `Error::<T>::NoPermission`: If the caller is not a manager of the
		///   pool.
		/// - `Error::<T>::NothingToRefund`: If there is nothing to refund.
		#[pallet::call_index(8)]
		#[pallet::weight(T::WeightInfo::start_refund(currency_count.to_owned()))]
		pub fn start_refund(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			let who = T::DefaultOrigin::ensure_origin(origin)?;

			let actual_currency_count = Self::do_start_refund(pool_id, currency_count, Some(&who))?;

			Ok(Some(T::WeightInfo::start_refund(actual_currency_count)).into())
		}

		/// Starts the refund process for a pool. The pool will be set to a
		/// refunding state. The origin requires force privileges.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring force privileges.
		/// - `pool_id`: The identifier of the pool to start the refund process
		///   for.
		/// - `currency_count`: The currency count in the pool, required for
		///   weight calculation.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `max_currencies`.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live state.
		/// - `Error::<T>::NoPermission`: If the caller is not a manager of the
		///   pool.
		/// - `Error::<T>::NothingToRefund`: If there is nothing to refund.
		#[pallet::call_index(9)]
		#[pallet::weight(T::WeightInfo::force_start_refund(currency_count.to_owned()))]
		pub fn force_start_refund(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			T::ForceOrigin::ensure_origin(origin)?;

			let actual_currency_count = Self::do_start_refund(pool_id, currency_count, None)?;

			Ok(Some(T::WeightInfo::force_start_refund(actual_currency_count)).into())
		}

		/// Refund an account. The account will be refunded with the collateral
		/// from the pool account.
		/// The amount of collateral to be refunded is calculated based on the
		/// amount of bonded tokens burned by the account in proportion to the
		/// total supply of bonded tokens.
		///
		/// # Parameters
		/// - `origin`: The origin of the call.
		/// - `pool_id`: The identifier of the pool.
		/// - `account`: The account to be refunded.
		/// - `asset_idx`: The index of the asset in the bonded currencies
		///   vector.
		/// - `currency_count`: The currency count in the pool, required for
		///   weight calculation.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `currency_count`.
		/// - `Error::<T>::NotRefunding`: If the pool is not in a refunding
		///   state.
		/// - `Error::<T>::IndexOutOfBounds`: If the asset index is out of
		///   bounds.
		/// - `Error::<T>::NothingToRefund`: If there is nothing to refund.
		///   Either no collateral or the account has no bonded tokens.
		/// - `Error::<T>::Internal`: If there is an internal error during the
		///   calculation.
		#[pallet::call_index(10)]
		#[pallet::weight(T::WeightInfo::refund_account(currency_count.to_owned()))]
		pub fn refund_account(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			account: AccountIdLookupOf<T>,
			asset_idx: u32,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			T::DefaultOrigin::ensure_origin(origin)?;
			let who = T::Lookup::lookup(account)?;

			let pool_details = Pools::<T>::get(&pool_id).ok_or(Error::<T>::PoolUnknown)?;

			let number_of_currencies = Self::get_currencies_number(&pool_details);

			ensure!(number_of_currencies <= currency_count, Error::<T>::CurrencyCount);

			ensure!(pool_details.state.is_refunding(), Error::<T>::NotRefunding);

			// get asset id from linked assets vector
			let asset_id: &FungiblesAssetIdOf<T> = pool_details
				.bonded_currencies
				.get(asset_idx.saturated_into::<usize>())
				.ok_or(Error::<T>::IndexOutOfBounds)?;

			let pool_account = pool_id.clone().into();

			// Choosing total_balance over reducible_balance to ensure that all funds are
			// distributed fairly; in case of any locks present on the pool account, this
			// could lead to refunds failing to execute. This case would have to be
			// resolved by governance, either by removing locks or force_destroying the
			// pool.
			let total_collateral_issuance =
				T::Collaterals::total_balance(pool_details.collateral.clone(), &pool_account);

			// nothing to distribute; refunding is complete, user should call start_destroy
			ensure!(
				total_collateral_issuance > CollateralBalanceOf::<T>::zero(),
				Error::<T>::NothingToRefund
			);

			//  remove any existing locks on the account prior to burning
			T::Fungibles::thaw(asset_id, &who)
				.map_err(|freeze_error| {
					log::info!(target: LOG_TARGET, "Failed to thaw account: {:?}", freeze_error);
					freeze_error.into()
				})
				.map_err(|_| TokenError::FundsUnavailable)?;

			// With amount = max_value(), this trait implementation burns the reducible
			// balance on the account and returns the actual amount burnt
			let burnt: U256 = T::Fungibles::burn_from(
				asset_id.clone(),
				&who,
				Bounded::max_value(),
				WithdrawalPrecision::BestEffort,
				Fortitude::Force,
			)?
			.into();

			ensure!(!burnt.is_zero(), TokenError::FundsUnavailable);

			let sum_of_issuances = pool_details
				.bonded_currencies
				.into_iter()
				.fold(U256::from(0u8), |sum, id| {
					sum.saturating_add(T::Fungibles::total_issuance(id).into())
				})
				// Add the burnt amount back to the sum of total supplies
				.checked_add(burnt)
				.ok_or(ArithmeticError::Overflow)?;

			let amount: CollateralBalanceOf<T> = burnt
				.checked_mul(total_collateral_issuance.into())
				// As long as the balance type is half the size of a U256, this won't overflow.
				.ok_or(ArithmeticError::Overflow)?
				.checked_div(sum_of_issuances)
				// Because sum_of_issuances >= burnt > 0, this is theoretically impossible
				.ok_or_else(|| {
					log::error!(
						target: LOG_TARGET,
						"Sum of issuance is zero. Pool_id: {:?}, account: {:?} Burnt: {:?}, Total Collateral Issuance: {:?}, Sum of Issuances: {:?}",
						pool_id,
						who,
						burnt,
						total_collateral_issuance,
						sum_of_issuances
					);
					Error::<T>::Internal
				})?
				.checked_into()
				// Also theoretically impossible, as the result must be <= total_collateral_issuance
				// if burnt <= sum_of_issuances, which should always hold true
				.ok_or_else(|| {
					log::error!(
						target: LOG_TARGET,
						"Could not cast U256 into CollateralCurrency. Pool_id: {:?}, account: {:?} Burnt: {:?}, Total Collateral Issuance: {:?}, Sum of Issuances: {:?}",
						pool_id,
						who,
						burnt,
						total_collateral_issuance,
						sum_of_issuances
					);
					Error::<T>::Internal
				})?;

			if amount.is_zero()
				|| T::Collaterals::can_deposit(pool_details.collateral.clone(), &who, amount, Provenance::Extant)
					== DepositConsequence::BelowMinimum
			{
				// Funds are burnt but the collateral received is not sufficient to be deposited
				// to the account. This is tolerated as otherwise we could have edge cases where
				// it's impossible to refund at least some accounts.
				return Ok(Some(T::WeightInfo::refund_account(currency_count.to_owned())).into());
			}

			let transferred = T::Collaterals::transfer(
				pool_details.collateral,
				&pool_account,
				&who,
				amount,
				Preservation::Expendable,
			)?;

			// if collateral or total supply drops to zero, refunding is complete
			// -> emit event
			if sum_of_issuances <= burnt || total_collateral_issuance <= transferred {
				Self::deposit_event(Event::RefundComplete { id: pool_id });
			}

			Ok(Some(T::WeightInfo::refund_account(currency_count.to_owned())).into())
		}

		/// Starts the destruction process for a pool. The pool will be set to a
		/// destroying state. The origin account must be a manager of the pool.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring the caller to be a
		///   manager of the pool.
		/// - `pool_id`: The identifier of the pool to be destroyed.
		/// - `currency_count`: The currency count in the pool, required for
		///   weight calculation.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `max_currencies`.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live or
		///   refunding state.
		/// - `Error::<T>::NoPermission`: If the caller is not the owner or
		///   manager of the pool.
		/// - `Error::<T>::LivePool`: If there are holders or collateral to
		///   distribute.
		#[pallet::call_index(11)]
		#[pallet::weight(T::WeightInfo::start_destroy(currency_count.to_owned()))]
		pub fn start_destroy(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			let who = T::DefaultOrigin::ensure_origin(origin)?;

			let actual_currency_count = Self::do_start_destroy_pool(pool_id, currency_count, false, Some(&who))?;

			Ok(Some(T::WeightInfo::start_destroy(actual_currency_count)).into())
		}

		/// Starts the destruction process for a pool. The pool will be set to a
		/// destroying state. The origin requires force privileges.
		///
		/// # Parameters
		/// - `origin`: The origin of the call, requiring force privileges.
		/// - `pool_id`: The identifier of the pool to be destroyed.
		/// - `currency_count`: The currency count in the pool, required for
		///   weight calculation.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `max_currencies`.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live or
		///   refunding state.
		/// - `Error::<T>::NoPermission`: If the caller is not the owner or
		///   manager of the pool.
		#[pallet::call_index(12)]
		#[pallet::weight(T::WeightInfo::force_start_destroy(currency_count.to_owned()))]
		pub fn force_start_destroy(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			T::ForceOrigin::ensure_origin(origin)?;

			let actual_currency_count = Self::do_start_destroy_pool(pool_id, currency_count, true, None)?;

			Ok(Some(T::WeightInfo::force_start_destroy(actual_currency_count)).into())
		}

		/// Finishes the destruction process for a pool. The pool will be
		/// removed from the storage and all leftover collateral and deposits
		/// will be refunded to the owner.
		///
		/// # Parameters
		/// - `origin`: The origin of the call.
		/// - `pool_id`: The identifier of the pool to be destroyed.
		/// - `currency_count`: The currency count in the pool, required for
		///   weight calculation.
		///
		/// # Returns
		/// - `DispatchResultWithPostInfo`: The result of the dispatch with the
		///   actual used weights.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `currency_count`.
		/// - `Error::<T>::LivePool`: If the pool is not in a destroying state
		///   or if there are any accounts left on any currency.
		#[pallet::call_index(13)]
		#[pallet::weight(T::WeightInfo::finish_destroy(currency_count.to_owned()))]
		pub fn finish_destroy(
			origin: OriginFor<T>,
			pool_id: T::PoolId,
			currency_count: u32,
		) -> DispatchResultWithPostInfo {
			T::DefaultOrigin::ensure_origin(origin)?;

			let pool_details = Pools::<T>::get(&pool_id).ok_or(Error::<T>::PoolUnknown)?;

			let n_currencies = Self::get_currencies_number(&pool_details);

			ensure!(n_currencies <= currency_count, Error::<T>::CurrencyCount);

			ensure!(pool_details.state.is_destroying(), Error::<T>::LivePool);

			for asset_id in pool_details.bonded_currencies {
				if T::Fungibles::asset_exists(asset_id.clone()) {
					// This would fail with an LiveAsset error if there are any accounts left on any
					// currency
					T::Fungibles::finish_destroy(asset_id)?;
				}
			}

			let pool_account = pool_id.clone().into();

			let total_collateral_issuance =
				T::Collaterals::total_balance(pool_details.collateral.clone(), &pool_account);

			if total_collateral_issuance > CollateralBalanceOf::<T>::zero() {
				T::Collaterals::transfer(
					pool_details.collateral,
					&pool_account,
					&pool_details.owner,
					total_collateral_issuance,
					Preservation::Expendable,
				)?;
			}

			Pools::<T>::remove(&pool_id);

			let hold_reason = Self::calculate_hold_reason(&pool_id)?;
			T::DepositCurrency::release(
				&hold_reason,
				&pool_details.owner,
				pool_details.deposit,
				WithdrawalPrecision::Exact,
			)?;

			Self::deposit_event(Event::Destroyed { id: pool_id });

			Ok(Some(T::WeightInfo::finish_destroy(n_currencies)).into())
		}
	}

	impl<T: Config> Pallet<T>
	where
		<CurveParameterTypeOf<T> as Fixed>::Bits:
			Copy + ToFixed + AddAssign + BitOrAssign + ShlAssign + TryFrom<U256> + TryInto<U256>,
		CollateralBalanceOf<T>: TryFrom<U256> + TryInto<U256>,
		FungiblesBalanceOf<T>: TryFrom<U256> + TryInto<U256>,
	{
		/// Calculates the collateral by the given curve and the normalized
		/// costs. High is the upper bound of the curve, low is the lower bound.
		/// The passive supply is the normalized total supply of all bonded
		/// currencies, excluding the active currency.
		///
		/// # Parameters
		/// - `low`: The lower bound of the curve.
		/// - `high`: The upper bound of the curve.
		/// - `passive_supply`: The normalized total supply of all bonded
		///   currencies, excluding the active currency.
		/// - `curve`: A reference to the curve used for calculation.
		/// - `collateral_currency_id`: The ID of the collateral currency.
		///
		/// # Returns
		/// - `Result<CollateralBalanceOf<T>, ArithmeticError>`: The calculated
		///   collateral or an error.
		///
		/// # Errors
		/// - `ArithmeticError`: If there is an operation overflowing,
		///   underflowing, or division by zero.
		fn calculate_collateral(
			low: CurveParameterTypeOf<T>,
			high: CurveParameterTypeOf<T>,
			passive_supply: PassiveSupply<CurveParameterTypeOf<T>>,
			curve: &Curve<CurveParameterTypeOf<T>>,
			collateral_currency_id: CollateralAssetIdOf<T>,
			round_kind: Round,
		) -> Result<CollateralBalanceOf<T>, ArithmeticError> {
			let normalized_costs = curve.calculate_costs(low, high, passive_supply)?;

			let denomination = T::Collaterals::decimals(collateral_currency_id);

			fixed_to_balance(normalized_costs, denomination, round_kind)
		}

		/// Calculates the normalized passive and active issuance for a pool.
		/// The active issuance is the issuance of the currency that is being
		/// minted or burned. The normalized value is generated by dividing the
		/// funds by the denomination.
		///
		/// # Parameters
		/// - `bonded_currencies`: A slice of bonded currency asset IDs.
		/// - `denomination`: The denomination to normalize the values.
		/// - `currency_idx`: The index of the currency being minted or burned.
		///
		/// # Returns
		/// - `Result<(CurveParameterTypeOf<T>,
		///   PassiveSupply<CurveParameterTypeOf<T>>), DispatchError>`: A tuple
		///   containing the active issuance and the normalized passive
		///   issuances.
		///
		/// # Errors
		/// - `ArithmeticError`: If there is an error during the conversion to
		///   fixed point.
		fn calculate_normalized_passive_issuance(
			bonded_currencies: &[FungiblesAssetIdOf<T>],
			denomination: u8,
			currency_idx: usize,
			round_kind: Round,
		) -> Result<(CurveParameterTypeOf<T>, PassiveSupply<CurveParameterTypeOf<T>>), DispatchError> {
			let mut normalized_total_issuances = bonded_currencies
				.iter()
				.map(|currency_id| {
					balance_to_fixed(
						T::Fungibles::total_issuance(currency_id.to_owned()),
						denomination,
						round_kind,
					)
				})
				.collect::<Result<Vec<CurveParameterTypeOf<T>>, ArithmeticError>>()?;

			let active_issuance = normalized_total_issuances.swap_remove(currency_idx);

			Ok((active_issuance, normalized_total_issuances))
		}

		/// Starts the refund process for a pool.
		/// The `maybe_check_manager` parameter is used to check if the caller
		/// is a manager. Fails if the pool is not live or there is nothing to
		/// refund.
		///
		/// # Parameters
		/// - `pool_id`: The identifier of the pool to start the refund process
		///   for.
		/// - `max_currencies`: The currency count in the pool, required for
		///   weight calculation.
		/// - `maybe_check_manager`: An optional parameter to check if the
		///   caller is a manager.
		///
		/// # Returns
		/// - `Result<u32, DispatchError>`: The number of currencies in the pool
		///   or an error.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `max_currencies`.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live state.
		/// - `Error::<T>::NoPermission`: If `maybe_check_manager` is not equal
		///   to the pool's manager. This check is skipped if
		///   `maybe_check_manager` is set to `None`.
		/// - `Error::<T>::NothingToRefund`: If there is nothing to refund.
		fn do_start_refund(
			pool_id: T::PoolId,
			max_currencies: u32,
			maybe_check_manager: Option<&AccountIdOf<T>>,
		) -> Result<u32, DispatchError> {
			let pool_details = Pools::<T>::get(&pool_id).ok_or(Error::<T>::PoolUnknown)?;

			let n_currencies = Self::get_currencies_number(&pool_details);

			ensure!(n_currencies <= max_currencies, Error::<T>::CurrencyCount);

			// refunding can only be triggered on a live pool
			ensure!(pool_details.state.is_live(), Error::<T>::PoolNotLive);

			if let Some(caller) = maybe_check_manager {
				ensure!(pool_details.is_manager(caller), Error::<T>::NoPermission);
			}

			let total_collateral_issuance =
				T::Collaterals::total_balance(pool_details.collateral.clone(), &pool_id.clone().into());
			// nothing to distribute
			ensure!(
				total_collateral_issuance > CollateralBalanceOf::<T>::zero(),
				Error::<T>::NothingToRefund
			);

			let has_holders = pool_details
				.bonded_currencies
				.iter()
				.any(|asset_id| T::Fungibles::total_issuance(asset_id.clone()) > FungiblesBalanceOf::<T>::zero());
			// no token holders to refund
			ensure!(has_holders, Error::<T>::NothingToRefund);

			// switch pool state to refunding
			let mut new_pool_details = pool_details;
			new_pool_details.state.start_refund();
			Pools::<T>::set(&pool_id, Some(new_pool_details));

			Self::deposit_event(Event::RefundingStarted { id: pool_id });

			Ok(n_currencies)
		}

		/// Starts the destruction process for a pool.
		/// This function is called by both the normal and forced start_destroy
		/// functions.
		///
		/// # Parameters
		/// - `pool_id`: The identifier of the pool to be destroyed.
		/// - `max_currencies`: The currency count in the pool, required for
		///   weight calculation.
		/// - `force_skip_refund`: A flag to skip the refund check.
		/// - `maybe_check_manager`: An optional parameter to check if the
		///   caller is a manager.
		///
		/// # Returns
		/// - `Result<u32, DispatchError>`: The number of currencies in the pool
		///   or an error.
		///
		/// # Errors
		/// - `Error::<T>::PoolUnknown`: If the pool does not exist.
		/// - `Error::<T>::CurrencyCount`: If the number of currencies exceeds
		///   `max_currencies`.
		/// - `Error::<T>::PoolNotLive`: If the pool is not in a live or
		///   refunding state.
		/// - `Error::<T>::NoPermission`: If the caller is not the owner or
		///   manager of the pool.
		/// - `Error::<T>::LivePool`: If there are holders or collateral to
		///   distribute.
		fn do_start_destroy_pool(
			pool_id: T::PoolId,
			max_currencies: u32,
			force_skip_refund: bool,
			maybe_check_manager: Option<&AccountIdOf<T>>,
		) -> Result<u32, DispatchError> {
			let pool_details = Pools::<T>::get(&pool_id).ok_or(Error::<T>::PoolUnknown)?;

			let n_currencies = Self::get_currencies_number(&pool_details);

			ensure!(n_currencies <= max_currencies, Error::<T>::CurrencyCount);

			ensure!(
				pool_details.state.is_live() || pool_details.state.is_refunding(),
				Error::<T>::PoolNotLive
			);

			if let Some(caller) = maybe_check_manager {
				ensure!(
					pool_details.is_owner(caller) || pool_details.is_manager(caller),
					Error::<T>::NoPermission
				);
			}

			if !force_skip_refund {
				let total_collateral_issuance =
					T::Collaterals::total_balance(pool_details.collateral.clone(), &pool_id.clone().into());

				if total_collateral_issuance > CollateralBalanceOf::<T>::zero() {
					let has_holders = pool_details.bonded_currencies.iter().any(|asset_id| {
						T::Fungibles::total_issuance(asset_id.clone()) > FungiblesBalanceOf::<T>::zero()
					});
					// destruction is only allowed when there are no holders or no collateral to
					// distribute
					ensure!(!has_holders, Error::<T>::LivePool);
				}
			}

			// cloning the currency ids now lets us avoid cloning the entire pool_details
			let bonded_currencies = pool_details.bonded_currencies.clone();

			// switch pool state to destroying
			let mut new_pool_details = pool_details;
			new_pool_details.state.start_destroy();
			Pools::<T>::set(&pool_id, Some(new_pool_details));

			// emit this event before the destruction started events are emitted by assets
			// deactivation
			Self::deposit_event(Event::DestructionStarted { id: pool_id });

			for asset_id in bonded_currencies {
				// Governance or other pallets using the fungibles trait can in theory destroy
				// an asset without this pallet knowing, so we check if it's still around
				if T::Fungibles::asset_exists(asset_id.clone()) {
					T::Fungibles::start_destroy(asset_id, None)?;
				}
			}

			Ok(n_currencies)
		}

		/// Gets the number of bonded currencies in a pool.
		///
		/// # Parameters
		/// - `pool_details`: A reference to the pool details.
		///
		/// # Returns
		/// - `u32`: The number of bonded currencies in the pool.
		pub(crate) fn get_currencies_number(pool_details: &PoolDetailsOf<T>) -> u32 {
			// bonded_currencies is a BoundedVec with maximum length MaxCurrenciesPerPool,
			// which is a u32; conversion to u32 must thus be lossless.
			pool_details.bonded_currencies.len().saturated_into()
		}

		/// Calculates the deposit required for a pool with the given number of
		/// currencies. This is the sum of the base deposit and the deposit per
		/// currency.
		///
		/// # Parameters
		/// - `n_currencies`: The number of currencies in the pool.
		///
		/// # Returns
		/// - `DepositBalanceOf<T>`: The total deposit required for the pool.
		pub(crate) fn calculate_pool_deposit<N: UniqueSaturatedInto<DepositBalanceOf<T>>>(
			n_currencies: N,
		) -> DepositBalanceOf<T> {
			T::BaseDeposit::get()
				.saturating_add(T::DepositPerCurrency::get().saturating_mul(n_currencies.saturated_into()))
		}

		/// Calculates the hold reason for a pool.
		pub(crate) fn calculate_hold_reason(pool_id: &T::PoolId) -> Result<T::RuntimeHoldReason, Error<T>> {
			let hold_reason = T::HoldReason::try_from(pool_id.to_owned()).map_err(|_| {
				log::error!(target: LOG_TARGET, "Failed to convert pool ID into a valid hold reason.");
				Error::<T>::Internal
			})?;

			Ok(T::RuntimeHoldReason::from(hold_reason))
		}
	}
}