Struct pallet_dapp_staking::AccountLedger

pub struct AccountLedger<UnlockingLen: Get<u32>> { /* private fields */ }

General info about an account’s lock & stakes.

Overview

The most complex part about this type are the staked and staked_future fields. To understand why the two fields exist and how they are used, it’s important to consider some facts:

• when an account stakes, the staked amount is only eligible for rewards from the next era
• all stakes are reset when a period ends - but this is done in a lazy fashion, account ledgers aren’t directly updated
• stake and unstake operations are allowed only if the account has claimed all pending rewards

In order to keep track of current era stake, and next era stake, two fields are needed. Since it’s not allowed to stake/unstake if there are pending rewards, it’s guaranteed that the staked and staked_future eras are always consecutive. In order to understand if stake is still valid, it’s enough to check the period field of either staked or staked_future.

Example

Scenario 1

• current era is 20, and current period is 1
• staked is equal to: { voting: 100, build_and_earn: 50, era: 5, period: 1 }
• staked_future is equal to: { voting: 100, build_and_earn: 100, era: 6, period: 1 }

The correct way to interpret this is:

• account had staked 150 in total in era 5
• account had increased their stake to 200 in total in era 6
• since then, era 6, account hadn’t staked or unstaked anything or hasn’t claimed any rewards
• since we’re in era 20 and period is still 1, the account’s stake for eras 7 to 20 is still 200

Scenario 2

• current era is 20, and current period is 1
• staked is equal to: { voting: 0, build_and_earn: 0, era: 0, period: 0 }
• staked_future is equal to: { voting: 0, build_and_earn: 350, era: 13, period: 1 }

The correct way to interpret this is:

• staked entry is empty
• account had called stake during era 12, and staked 350 for the next era
• account hadn’t staked, unstaked or claimed rewards since then
• since we’re in era 20 and period is still 1, the account’s stake for eras 13 to 20 is still 350

Scenario 3

• current era is 30, and current period is 2
• period 1 ended after era 24, and period 2 started in era 25
• staked is equal to: { voting: 100, build_and_earn: 300, era: 20, period: 1 }
• staked_future is equal to None

The correct way to interpret this is:

• in era 20, account had claimed rewards for the past eras, so only the staked entry remained
• since then, account hadn’t staked, unstaked or claimed rewards
• period 1 ended in era 24, which means that after that era, the staked entry is no longer valid
• account had staked 400 in total from era 20 up to era 24 (inclusive)
• account’s stake in era 25 is zero

Implementations

impl<UnlockingLen> AccountLedger<UnlockingLen>

where UnlockingLen: Get<u32>,

pub fn locked(&self) -> Balance

How much active locked amount an account has. This can be used for staking.

pub fn unlocking_chunks(&self) -> &[UnlockingChunk]

Unlocking chunks.

pub fn is_empty(&self) -> bool

Empty if no locked/unlocking/staked info exists.

pub fn active_locked_amount(&self) -> Balance

Returns active locked amount. If zero, means that associated account hasn’t got any active locked funds.

It is possible that some funds are undergoing the unlocking period, but they aren’t considered active in that case.

pub fn unlocking_amount(&self) -> Balance

Returns unlocking amount. If zero, means that associated account hasn’t got any unlocking chunks.

pub fn total_locked_amount(&self) -> Balance

Total locked amount by the user. Includes both active locked amount & unlocking amount.

pub fn add_lock_amount(&mut self, amount: Balance)

Adds the specified amount to the total locked amount.

pub fn subtract_lock_amount(&mut self, amount: Balance)

Subtracts the specified amount of the total locked amount.

pub fn add_unlocking_chunk( &mut self, amount: Balance, unlock_block: BlockNumber ) -> Result<(), AccountLedgerError>

Adds the specified amount to the unlocking chunks.

If entry for the specified block already exists, it’s updated.

If entry for the specified block doesn’t exist, it’s created and insertion is attempted. In case vector has no more capacity, error is returned, and whole operation is a noop.

pub fn unlockable_amount(&self, current_period: PeriodNumber) -> Balance

Amount available for unlocking.

pub fn claim_unlocked(&mut self, current_block_number: BlockNumber) -> Balance

Claims all of the fully unlocked chunks, and returns the total claimable amount.

pub fn consume_unlocking_chunks(&mut self) -> Balance

Consumes all of the unlocking chunks, and returns the total amount being unlocked.

pub fn stakeable_amount(&self, active_period: PeriodNumber) -> Balance

Amount that is available for staking.

This is equal to the total active locked amount, minus the staked amount already active.

pub fn staked_amount(&self, active_period: PeriodNumber) -> Balance

Amount that is staked, in respect to the currently active period.

pub fn staked_amount_for_type( &self, subperiod: Subperiod, period: PeriodNumber ) -> Balance

How much is staked for the specified subperiod, in respect to the specified era.

pub fn add_stake_amount( &mut self, amount: Balance, current_era: EraNumber, current_period_info: PeriodInfo ) -> Result<(), AccountLedgerError>

Adds the specified amount to total staked amount, if possible.

Staking can only be done for the ongoing period, and era.

1. The period requirement enforces staking in the ongoing period.
2. The era requirement enforces staking in the ongoing era.

The 2nd condition is needed to prevent stakers from building a significant history of stakes, without claiming the rewards. So if a historic era exists as an entry, stakers will first need to claim the pending rewards, before they can stake again.

Additionally, the staked amount must not exceed what’s available for staking.

pub fn unstake_amount( &mut self, amount: Balance, current_era: EraNumber, current_period_info: PeriodInfo ) -> Result<(), AccountLedgerError>

Subtracts the specified amount from the total staked amount, if possible.

Unstake can only be called if the entry for the current era exists. In case historic entry exists, rewards first need to be claimed, before unstaking is possible. Similar as with stake functionality, this is to prevent staker from building a significant history of stakes.

pub fn staked_period(&self) -> Option<PeriodNumber>

Period for which account has staking information or None if no staking information exists.

pub fn earliest_staked_era(&self) -> Option<EraNumber>

Earliest era for which the account has staking information or None if no staking information exists.

pub fn maybe_cleanup_expired( &mut self, valid_threshold_period: PeriodNumber ) -> bool

Cleanup staking information if it has expired.

Args

valid_threshold_period - last period for which entries can still be considered valid.

true if any change was made, false otherwise.

pub fn claim_up_to_era( &mut self, era: EraNumber, period_end: Option<EraNumber> ) -> Result<EraStakePairIter, AccountLedgerError>

‘Claim’ rewards up to the specified era. Returns an iterator over the (era, amount) pairs, where amount describes the staked amount eligible for reward in the appropriate era.

If period_end is provided, it’s used to determine whether all applicable chunks have been claimed.

Trait Implementations

impl<UnlockingLen: Get<u32>> Clone for AccountLedger<UnlockingLen>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<UnlockingLen: Get<u32>> Debug for AccountLedger<UnlockingLen>

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

Formats the value using the given formatter.

impl<UnlockingLen: Get<u32>> Decode for AccountLedger<UnlockingLen>

where BoundedVec<UnlockingChunk, UnlockingLen>: Decode,

fn decode<__CodecInputEdqy: Input>( __codec_input_edqy: &mut __CodecInputEdqy ) -> Result<Self, Error>

Attempt to deserialise the value from input.

fn decode_into<I>( input: &mut I, dst: &mut MaybeUninit<Self> ) -> Result<DecodeFinished, Error>

where I: Input,

Attempt to deserialize the value from input into a pre-allocated piece of memory.

fn skip<I>(input: &mut I) -> Result<(), Error>

where I: Input,

Attempt to skip the encoded value from input.

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type.

impl<UnlockingLen: Get<u32>> Default for AccountLedger<UnlockingLen>

fn default() -> Self

Returns the “default value” for a type.

impl<UnlockingLen: Get<u32>> Encode for AccountLedger<UnlockingLen>

where BoundedVec<UnlockingChunk, UnlockingLen>: Encode,

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding.

fn encode_to<__CodecOutputEdqy: Output + ?Sized>( &self, __codec_dest_edqy: &mut __CodecOutputEdqy )

Convert self to a slice and append it to the destination.

fn encode(&self) -> Vec<u8>

Convert self to an owned vector.

fn using_encoded<R, F>(&self, f: F) -> R

where F: FnOnce(&[u8]) -> R,

Convert self to a slice and then invoke the given closure with it.

fn encoded_size(&self) -> usize

Calculates the encoded size.

impl<UnlockingLen: Get<u32>> MaxEncodedLen for AccountLedger<UnlockingLen>

where BoundedVec<UnlockingChunk, UnlockingLen>: MaxEncodedLen,

fn max_encoded_len() -> usize

Upper bound, in bytes, of the maximum encoded size of this item.

impl<UnlockingLen: Get<u32>> PartialEq for AccountLedger<UnlockingLen>

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<UnlockingLen> TypeInfo for AccountLedger<UnlockingLen>

where BoundedVec<UnlockingChunk, UnlockingLen>: TypeInfo + 'static, UnlockingLen: Get<u32> + 'static,

type Identity = AccountLedger<UnlockingLen>

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.

impl<UnlockingLen: Get<u32>> EncodeLike for AccountLedger<UnlockingLen>

where BoundedVec<UnlockingChunk, UnlockingLen>: Encode,

impl<UnlockingLen: Get<u32>> Eq for AccountLedger<UnlockingLen>