Struct pallet_nomination_pools::pallet::Pallet

pub struct Pallet<T>(_);

The Pallet struct, the main type that implements traits and standalone functions within the pallet.

Implementations

impl<T: Config> Pallet<T>

pub fn join( origin: OriginFor<T>, amount: BalanceOf<T>, pool_id: PoolId ) -> DispatchResult

Stake funds with a pool. The amount to bond is transferred from the member to the pools account and immediately increases the pools bond.

Note

• An account can only be a member of a single pool.
• An account cannot join the same pool multiple times.
• This call will not dust the member account, so the member must have at least existential deposit + amount in their account.
• Only a pool with PoolState::Open can be joined

pub fn bond_extra( origin: OriginFor<T>, extra: BondExtra<BalanceOf<T>> ) -> DispatchResult

Bond extra more funds from origin into the pool to which they already belong.

Additional funds can come from either the free balance of the account, of from the accumulated rewards, see BondExtra.

Bonding extra funds implies an automatic payout of all pending rewards as well. See bond_extra_other to bond pending rewards of other members.

pub fn claim_payout(origin: OriginFor<T>) -> DispatchResult

A bonded member can use this to claim their payout based on the rewards that the pool has accumulated since their last claimed payout (OR since joining if this is their first time claiming rewards). The payout will be transferred to the member’s account.

The member will earn rewards pro rata based on the members stake vs the sum of the members in the pools stake. Rewards do not “expire”.

See claim_payout_other to caim rewards on bahalf of some other pool member.

pub fn unbond( origin: OriginFor<T>, member_account: <<T as Config>::Lookup as StaticLookup>::Source, unbonding_points: BalanceOf<T> ) -> DispatchResult

Unbond up to unbonding_points of the member_account’s funds from the pool. It implicitly collects the rewards one last time, since not doing so would mean some rewards would be forfeited.

Under certain conditions, this call can be dispatched permissionlessly (i.e. by any account).

Conditions for a permissionless dispatch.

• The pool is blocked and the caller is either the root or bouncer. This is refereed to as a kick.
• The pool is destroying and the member is not the depositor.
• The pool is destroying, the member is the depositor and no other members are in the pool.

Conditions for permissioned dispatch (i.e. the caller is also the

member_account):

• The caller is not the depositor.
• The caller is the depositor, the pool is destroying and no other members are in the pool.

Note

If there are too many unlocking chunks to unbond with the pool account, Call::pool_withdraw_unbonded can be called to try and minimize unlocking chunks. The StakingInterface::unbond will implicitly call Call::pool_withdraw_unbonded to try to free chunks if necessary (ie. if unbound was called and no unlocking chunks are available). However, it may not be possible to release the current unlocking chunks, in which case, the result of this call will likely be the NoMoreChunks error from the staking system.

pub fn pool_withdraw_unbonded( origin: OriginFor<T>, pool_id: PoolId, num_slashing_spans: u32 ) -> DispatchResult

Call withdraw_unbonded for the pools account. This call can be made by any account.

This is useful if their are too many unlocking chunks to call unbond, and some can be cleared by withdrawing. In the case there are too many unlocking chunks, the user would probably see an error like NoMoreChunks emitted from the staking system when they attempt to unbond.

pub fn withdraw_unbonded( origin: OriginFor<T>, member_account: <<T as Config>::Lookup as StaticLookup>::Source, num_slashing_spans: u32 ) -> DispatchResultWithPostInfo

Withdraw unbonded funds from member_account. If no bonded funds can be unbonded, an error is returned.

Under certain conditions, this call can be dispatched permissionlessly (i.e. by any account).

Conditions for a permissionless dispatch

• The pool is in destroy mode and the target is not the depositor.
• The target is the depositor and they are the only member in the sub pools.
• The pool is blocked and the caller is either the root or bouncer.

Conditions for permissioned dispatch

• The caller is the target and they are not the depositor.

Note

If the target is the depositor, the pool will be destroyed.

pub fn create( origin: OriginFor<T>, amount: BalanceOf<T>, root: <<T as Config>::Lookup as StaticLookup>::Source, nominator: <<T as Config>::Lookup as StaticLookup>::Source, bouncer: <<T as Config>::Lookup as StaticLookup>::Source ) -> DispatchResult

Create a new delegation pool.

Arguments

• amount - The amount of funds to delegate to the pool. This also acts of a sort of deposit since the pools creator cannot fully unbond funds until the pool is being destroyed.
• index - A disambiguation index for creating the account. Likely only useful when creating multiple pools in the same extrinsic.
• root - The account to set as PoolRoles::root.
• nominator - The account to set as the PoolRoles::nominator.
• bouncer - The account to set as the PoolRoles::bouncer.

Note

In addition to amount, the caller will transfer the existential deposit; so the caller needs at have at least amount + existential_deposit transferrable.

pub fn create_with_pool_id( origin: OriginFor<T>, amount: BalanceOf<T>, root: <<T as Config>::Lookup as StaticLookup>::Source, nominator: <<T as Config>::Lookup as StaticLookup>::Source, bouncer: <<T as Config>::Lookup as StaticLookup>::Source, pool_id: PoolId ) -> DispatchResult

Create a new delegation pool with a previously used pool id

Arguments

same as create with the inclusion of

• pool_id - `A valid PoolId.

pub fn nominate( origin: OriginFor<T>, pool_id: PoolId, validators: Vec<T::AccountId> ) -> DispatchResult

Nominate on behalf of the pool.

The dispatch origin of this call must be signed by the pool nominator or the pool root role.

This directly forward the call to the staking pallet, on behalf of the pool bonded account.

pub fn set_state( origin: OriginFor<T>, pool_id: PoolId, state: PoolState ) -> DispatchResult

Set a new state for the pool.

If a pool is already in the Destroying state, then under no condition can its state change again.

The dispatch origin of this call must be either:

1. signed by the bouncer, or the root role of the pool,
2. if the pool conditions to be open are NOT met (as described by ok_to_be_open), and then the state of the pool can be permissionlessly changed to Destroying.

pub fn set_metadata( origin: OriginFor<T>, pool_id: PoolId, metadata: Vec<u8> ) -> DispatchResult

Set a new metadata for the pool.

The dispatch origin of this call must be signed by the bouncer, or the root role of the pool.

pub fn set_configs( origin: OriginFor<T>, min_join_bond: ConfigOp<BalanceOf<T>>, min_create_bond: ConfigOp<BalanceOf<T>>, max_pools: ConfigOp<u32>, max_members: ConfigOp<u32>, max_members_per_pool: ConfigOp<u32>, global_max_commission: ConfigOp<Perbill> ) -> DispatchResult

Update configurations for the nomination pools. The origin for this call must be Root.

Arguments

• min_join_bond - Set MinJoinBond.
• min_create_bond - Set MinCreateBond.
• max_pools - Set MaxPools.
• max_members - Set MaxPoolMembers.
• max_members_per_pool - Set MaxPoolMembersPerPool.
• global_max_commission - Set GlobalMaxCommission.

pub fn update_roles( origin: OriginFor<T>, pool_id: PoolId, new_root: ConfigOp<T::AccountId>, new_nominator: ConfigOp<T::AccountId>, new_bouncer: ConfigOp<T::AccountId> ) -> DispatchResult

Update the roles of the pool.

The root is the only entity that can change any of the roles, including itself, excluding the depositor, who can never change.

It emits an event, notifying UIs of the role change. This event is quite relevant to most pool members and they should be informed of changes to pool roles.

pub fn chill(origin: OriginFor<T>, pool_id: PoolId) -> DispatchResult

Chill on behalf of the pool.

The dispatch origin of this call must be signed by the pool nominator or the pool root role, same as Pallet::nominate.

This directly forward the call to the staking pallet, on behalf of the pool bonded account.

pub fn bond_extra_other( origin: OriginFor<T>, member: <<T as Config>::Lookup as StaticLookup>::Source, extra: BondExtra<BalanceOf<T>> ) -> DispatchResult

origin bonds funds from extra for some pool member member into their respective pools.

origin can bond extra funds from free balance or pending rewards when origin == other.

In the case of origin != other, origin can only bond extra pending rewards of other members assuming set_claim_permission for the given member is PermissionlessAll or PermissionlessCompound.

pub fn set_claim_permission( origin: OriginFor<T>, permission: ClaimPermission ) -> DispatchResult

Allows a pool member to set a claim permission to allow or disallow permissionless bonding and withdrawing.

By default, this is Permissioned, which implies only the pool member themselves can claim their pending rewards. If a pool member wishes so, they can set this to PermissionlessAll to allow any account to claim their rewards and bond extra to the pool.

Arguments

• origin - Member of a pool.
• actor - Account to claim reward. // improve this

pub fn claim_payout_other( origin: OriginFor<T>, other: T::AccountId ) -> DispatchResult

origin can claim payouts on some pool member other’s behalf.

Pool member other must have a PermissionlessAll or PermissionlessWithdraw in order for this call to be successful.

pub fn set_commission( origin: OriginFor<T>, pool_id: PoolId, new_commission: Option<(Perbill, T::AccountId)> ) -> DispatchResult

Set the commission of a pool. Both a commission percentage and a commission payee must be provided in the current tuple. Where a current of None is provided, any current commission will be removed.

• If a None is supplied to new_commission, existing commission will be removed.

pub fn set_commission_max( origin: OriginFor<T>, pool_id: PoolId, max_commission: Perbill ) -> DispatchResult

Set the maximum commission of a pool.

• Initial max can be set to any Perbill, and only smaller values thereafter.
• Current commission will be lowered in the event it is higher than a new max commission.

pub fn set_commission_change_rate( origin: OriginFor<T>, pool_id: PoolId, change_rate: CommissionChangeRate<BlockNumberFor<T>> ) -> DispatchResult

Set the commission change rate for a pool.

Initial change rate is not bounded, whereas subsequent updates can only be more restrictive than the current.

pub fn claim_commission(origin: OriginFor<T>, pool_id: PoolId) -> DispatchResult

Claim pending commission.

The dispatch origin of this call must be signed by the root role of the pool. Pending commission is paid out and added to total claimed commission`. Total pending commission is reset to zero. the current.

impl<T: Config> Pallet<T>

pub fn depositor_min_bond() -> BalanceOf<T>

The amount of bond that MUST REMAIN IN BONDED in ALL POOLS.

It is the responsibility of the depositor to put these funds into the pool initially. Upon unbond, they can never unbond to a value below this amount.

It is essentially max { MinNominatorBond, MinCreateBond, MinJoinBond }, where the former is coming from the staking pallet and the latter two are configured in this pallet.

pub fn dissolve_pool(bonded_pool: BondedPool<T>)

Remove everything related to the given bonded pool.

Metadata and all of the sub-pools are also deleted. All accounts are dusted and the leftover of the reward account is returned to the depositor.

pub fn create_bonded_account(id: PoolId) -> T::AccountId

Create the main, bonded account of a pool with the given id.

pub fn create_reward_account(id: PoolId) -> T::AccountId

Create the reward account of a pool with the given id.

pub fn do_try_state(level: u8) -> Result<(), TryRuntimeError>

Ensure the correctness of the state of this pallet.

This should be valid before or after each state transition of this pallet.

Invariants:

First, let’s consider pools:

• BondedPools and RewardPools must all have the EXACT SAME key-set.
• SubPoolsStorage must be a subset of the above superset.
• Metadata keys must be a subset of the above superset.
• the count of the above set must be less than MaxPools.

Then, considering members as well:

• each BondedPool.member_counter must be:
  • correct (compared to actual count of member who have .pool_id this pool)
  • less than MaxPoolMembersPerPool.
• each member.pool_id must correspond to an existing BondedPool.id (which implies the existence of the reward pool as well).
• count of all members must be less than MaxPoolMembers.

Then, considering unbonding members:

for each pool:

• sum of the balance that’s tracked in all unbonding pools must be the same as the unbonded balance of the main account, as reported by the staking interface.
• sum of the balance that’s tracked in all unbonding pools, plus the bonded balance of the main account should be less than or qual to the total balance of the main account.

Sanity check level

To cater for tests that want to escape parts of these checks, this function is split into multiple levels, where the higher the level, the more checks we performs. So, try_state(255) is the strongest sanity check, and 0 performs no checks.

pub fn fully_unbond( origin: OriginFor<T>, member: T::AccountId ) -> DispatchResult

Fully unbond the shares of member, when executed from origin.

This is useful for backwards compatibility with the majority of tests that only deal with full unbonding, not partial unbonding.

impl<T: Config> Pallet<T>

pub fn api_pending_rewards(who: T::AccountId) -> Option<BalanceOf<T>>

Returns the pending rewards for the specified who account.

In the case of error, None is returned. Used by runtime API.

pub fn api_points_to_balance( pool_id: PoolId, points: BalanceOf<T> ) -> BalanceOf<T>

Returns the points to balance conversion for a specified pool.

If the pool ID does not exist, it returns 0 ratio points to balance. Used by runtime API.

pub fn api_balance_to_points( pool_id: PoolId, new_funds: BalanceOf<T> ) -> BalanceOf<T>

Returns the equivalent new_funds balance to point conversion for a specified pool.

If the pool ID does not exist, returns 0 ratio balance to points. Used by runtime API.

Trait Implementations

impl<T: Config> Callable<T> for Pallet<T>

type RuntimeCall = Call<T>

impl<T> Clone for Pallet<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Pallet<T>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<<Pallet<Runtime> as Callable<Runtime>>::RuntimeCall> for RuntimeCall

fn from(call: CallableCallFor<Pools, Runtime>) -> Self

Converts to this type from the input type.

impl<T: Config> GetStorageVersion for Pallet<T>

type CurrentStorageVersion = StorageVersion

This will be filled out by the pallet macro.

fn current_storage_version() -> Self::CurrentStorageVersion

Returns the current storage version as supported by the pallet.

fn on_chain_storage_version() -> StorageVersion

Returns the on-chain storage version of the pallet as stored in the storage.

impl<T: Config> Hooks<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for Pallet<T>

fn try_state(_n: BlockNumberFor<T>) -> Result<(), TryRuntimeError>

Execute the sanity checks of this pallet, per block.

fn integrity_test()

Check the integrity of this pallet’s configuration.

fn on_initialize(_n: BlockNumber) -> Weight

Block initialization hook. This is called at the very beginning of block execution.

fn on_finalize(_n: BlockNumber)

Block finalization hook. This is called at the very end of block execution.

fn on_idle(_n: BlockNumber, _remaining_weight: Weight) -> Weight

Hook to consume a block’s idle time. This will run when the block is being finalized (before Hooks::on_finalize).

fn on_runtime_upgrade() -> Weight

Hook executed when a code change (aka. a “runtime upgrade”) is detected by FRAME.

fn pre_upgrade() -> Result<Vec<u8, Global>, DispatchError>

Execute some pre-checks prior to a runtime upgrade.

fn post_upgrade(_state: Vec<u8, Global>) -> Result<(), DispatchError>

Execute some post-checks after a runtime upgrade.

fn offchain_worker(_n: BlockNumber)

Implementing this function on a pallet allows you to perform long-running tasks that are dispatched as separate threads, and entirely independent of the main wasm runtime.

impl<T: Config> IntegrityTest for Pallet<T>

fn integrity_test()

See Hooks::integrity_test.

impl IsSubType<<Pallet<Runtime> as Callable<Runtime>>::RuntimeCall> for RuntimeCall

fn is_sub_type(&self) -> Option<&CallableCallFor<Pools, Runtime>>

Returns Some(_) if self is an instance of sub type T.

impl<T: Config> OffchainWorker<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for Pallet<T>

fn offchain_worker(n: BlockNumberFor<T>)

This function is being called after every block import (when fully synced).

impl<T: Config> OnFinalize<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for Pallet<T>

fn on_finalize(n: BlockNumberFor<T>)

See Hooks::on_finalize.

impl<T: Config> OnGenesis for Pallet<T>

fn on_genesis()

Something that should happen at genesis.

impl<T: Config> OnIdle<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for Pallet<T>

fn on_idle(n: BlockNumberFor<T>, remaining_weight: Weight) -> Weight

See Hooks::on_idle.

impl<T: Config> OnInitialize<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for Pallet<T>

fn on_initialize(n: BlockNumberFor<T>) -> Weight

See Hooks::on_initialize.

impl<T: Config> OnRuntimeUpgrade for Pallet<T>

fn on_runtime_upgrade() -> Weight

See Hooks::on_runtime_upgrade.

fn pre_upgrade() -> Result<Vec<u8>, TryRuntimeError>

See Hooks::pre_upgrade.

fn post_upgrade(state: Vec<u8>) -> Result<(), TryRuntimeError>

See Hooks::post_upgrade.

fn try_on_runtime_upgrade(checks: bool) -> Result<Weight, DispatchError>

The expected and default behavior of this method is to handle executing pre_upgrade -> on_runtime_upgrade -> post_upgrade hooks for a migration.

impl<T: Config> OnStakingUpdate<<T as Config>::AccountId, <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance> for Pallet<T>

fn on_slash( pool_account: &T::AccountId, slashed_bonded: BalanceOf<T>, slashed_unlocking: &BTreeMap<EraIndex, BalanceOf<T>> )

Fired when a staker is slashed.

fn on_stake_update(_who: &AccountId, _prev_stake: Option<Stake<Balance>>)

Fired when the stake amount of someone updates.

fn on_nominator_add(_who: &AccountId)

Fired when someone sets their intention to nominate.

fn on_nominator_update( _who: &AccountId, _prev_nominations: Vec<AccountId, Global> )

Fired when an existing nominator updates their nominations.

fn on_nominator_remove(_who: &AccountId, _nominations: Vec<AccountId, Global>)

Fired when someone removes their intention to nominate, either due to chill or validating.

fn on_validator_add(_who: &AccountId)

Fired when someone sets their intention to validate.

fn on_validator_update(_who: &AccountId)

Fired when an existing validator updates their preferences.

fn on_validator_remove(_who: &AccountId)

Fired when someone removes their intention to validate, either due to chill or nominating.

fn on_unstake(_who: &AccountId)

Fired when someone is fully unstaked.

impl<T: Config> PalletInfoAccess for Pallet<T>

fn index() -> usize

Index of the pallet as configured in the runtime.

fn name() -> &'static str

Name of the pallet as configured in the runtime.

fn module_name() -> &'static str

Name of the Rust module containing the pallet.

fn crate_version() -> CrateVersion

Version of the crate containing the pallet.

impl<T: Config> PalletsInfoAccess for Pallet<T>

fn count() -> usize

The number of pallets’ information that this type represents.

fn infos() -> Vec<PalletInfoData>

All of the pallets’ information that this type represents.

impl<T> PartialEq<Pallet<T>> for Pallet<T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Config> StorageInfoTrait for Pallet<T>

fn storage_info() -> Vec<StorageInfo>

impl<T: Config> TryState<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for Pallet<T>

fn try_state( n: BlockNumberFor<T>, _s: TryStateSelect ) -> Result<(), TryRuntimeError>

Execute the state checks.

impl<T: Config> WhitelistedStorageKeys for Pallet<T>

fn whitelisted_storage_keys() -> Vec<TrackedStorageKey>

Returns a Vec<TrackedStorageKey> indicating the storage keys that should be whitelisted during benchmarking. This means that those keys will be excluded from the benchmarking performance calculation.

impl<T> Eq for Pallet<T>