Module 0x3::staking_pool

• Resource StakingPoolV1
• Struct PoolTokenExchangeRate
• Resource StakedIota
• Constants
• Function new
• Function request_add_stake
• Function request_withdraw_stake
• Function withdraw_from_principal
• Function unwrap_staked_iota
• Function deposit_rewards
• Function process_pending_stakes_and_withdraws
• Function process_pending_stake_withdraw
• Function process_pending_stake
• Function withdraw_rewards
• Function activate_staking_pool
• Function deactivate_staking_pool
• Function iota_balance
• Function pool_id
• Function staked_iota_amount
• Function stake_activation_epoch
• Function is_preactive
• Function is_inactive
• Function split
• Function split_staked_iota
• Function join_staked_iota
• Function is_equal_staking_metadata
• Function pool_token_exchange_rate_at_epoch
• Function pending_stake_amount
• Function pending_stake_withdraw_amount
• Function exchange_rates
• Function iota_amount
• Function pool_token_amount
• Function is_preactive_at_epoch
• Function get_iota_amount
• Function get_token_amount
• Function initial_exchange_rate
• Function check_balance_invariants

use 0x1::option;
use 0x1::u64;
use 0x2::bag;
use 0x2::balance;
use 0x2::iota;
use 0x2::object;
use 0x2::table;
use 0x2::transfer;
use 0x2::tx_context;

Resource StakingPoolV1

A staking pool embedded in each validator struct in the system state object.

struct StakingPoolV1 has store, key

Fields

id: object::UID

activation_epoch: option::Option<u64>

The epoch at which this pool became active. The value is None if the pool is pre-active and Some(<epoch_number>) if active or inactive.

deactivation_epoch: option::Option<u64>

The epoch at which this staking pool ceased to be active. None = {pre-active, active}, Some(<epoch_number>) if in-active, and it was de-activated at epoch <epoch_number>.

iota_balance: u64

The total number of IOTA tokens in this pool, including the IOTA in the rewards_pool, as well as in all the principal in the StakedIota object, updated at epoch boundaries.

rewards_pool: balance::Balance<iota::IOTA>

The epoch stake rewards will be added here at the end of each epoch.

pool_token_balance: u64

Total number of pool tokens issued by the pool.

exchange_rates: table::Table<u64, staking_pool::PoolTokenExchangeRate>

Exchange rate history of previous epochs. Key is the epoch number. The entries start from the activation_epoch of this pool and contains exchange rates at the beginning of each epoch, i.e., right after the rewards for the previous epoch have been deposited into the pool.

pending_stake: u64

Pending stake amount for this epoch, emptied at epoch boundaries.

pending_total_iota_withdraw: u64

Pending stake withdrawn during the current epoch, emptied at epoch boundaries. This includes both the principal and rewards IOTA withdrawn.

pending_pool_token_withdraw: u64

Pending pool token withdrawn during the current epoch, emptied at epoch boundaries.

extra_fields: bag::Bag

Any extra fields that's not defined statically.

Struct PoolTokenExchangeRate

Struct representing the exchange rate of the stake pool token to IOTA.

struct PoolTokenExchangeRate has copy, drop, store

Fields

iota_amount: u64

pool_token_amount: u64

Resource StakedIota

A self-custodial object holding the staked IOTA tokens.

struct StakedIota has store, key

Fields

id: object::UID

pool_id: object::ID

ID of the staking pool we are staking with.

stake_activation_epoch: u64

The epoch at which the stake becomes active.

principal: balance::Balance<iota::IOTA>

The staked IOTA tokens.

Constants

const EActivationOfInactivePool: u64 = 16;

const EDeactivationOfInactivePool: u64 = 11;

const EDelegationOfZeroIota: u64 = 17;

const EDelegationToInactivePool: u64 = 10;

const EDestroyNonzeroBalance: u64 = 5;

const EIncompatibleStakedIota: u64 = 12;

const EInsufficientIotaTokenBalance: u64 = 3;

const EInsufficientPoolTokenBalance: u64 = 0;

const EInsufficientRewardsPoolBalance: u64 = 4;

const EPendingDelegationDoesNotExist: u64 = 8;

const EPoolAlreadyActive: u64 = 14;

const EPoolNotPreactive: u64 = 15;

const EStakedIotaBelowThreshold: u64 = 18;

const ETokenBalancesDoNotMatchExchangeRate: u64 = 9;

const ETokenTimeLockIsSome: u64 = 6;

const EWithdrawAmountCannotBeZero: u64 = 2;

const EWithdrawalInSameEpoch: u64 = 13;

const EWrongDelegation: u64 = 7;

const EWrongPool: u64 = 1;

StakedIota objects cannot be split to below this amount.

const MIN_STAKING_THRESHOLD: u64 = 1000000000;

Function new

Create a new, empty staking pool.

public(friend) fun new(ctx: &mut tx_context::TxContext): staking_pool::StakingPoolV1

Implementation

public(package) fun new(ctx: &mut TxContext) : StakingPoolV1 {
let exchange_rates = table::new(ctx);
StakingPoolV1 {
id: object::new(ctx),
activation_epoch: option::none(),
deactivation_epoch: option::none(),
iota_balance: 0,
rewards_pool: balance::zero(),
pool_token_balance: 0,
exchange_rates,
pending_stake: 0,
pending_total_iota_withdraw: 0,
pending_pool_token_withdraw: 0,
extra_fields: bag::new(ctx),
}
}

Function request_add_stake

Request to stake to a staking pool. The stake starts counting at the beginning of the next epoch,

public(friend) fun request_add_stake(pool: &mut staking_pool::StakingPoolV1, stake: balance::Balance<iota::IOTA>, stake_activation_epoch: u64, ctx: &mut tx_context::TxContext): staking_pool::StakedIota

Implementation

public(package) fun request_add_stake(
pool: &mut StakingPoolV1,
stake: Balance<IOTA>,
stake_activation_epoch: u64,
ctx: &mut TxContext
) : StakedIota {
let iota_amount = stake.value();
assert!(!is_inactive(pool), EDelegationToInactivePool);
assert!(iota_amount > 0, EDelegationOfZeroIota);
let staked_iota = StakedIota {
id: object::new(ctx),
pool_id: object::id(pool),
stake_activation_epoch,
principal: stake,
};
pool.pending_stake = pool.pending_stake + iota_amount;
staked_iota
}

Function request_withdraw_stake

Request to withdraw the given stake plus rewards from a staking pool. Both the principal and corresponding rewards in IOTA are withdrawn. A proportional amount of pool token withdraw is recorded and processed at epoch change time.

public(friend) fun request_withdraw_stake(pool: &mut staking_pool::StakingPoolV1, staked_iota: staking_pool::StakedIota, ctx: &tx_context::TxContext): balance::Balance<iota::IOTA>

Implementation

public(package) fun request_withdraw_stake(
pool: &mut StakingPoolV1,
staked_iota: StakedIota,
ctx: &TxContext
) : Balance<IOTA> {
// stake is inactive
if (staked_iota.stake_activation_epoch > ctx.epoch()) {
let principal = unwrap_staked_iota(staked_iota);
// Stake for preactive validators is always processed immediately and not added to the pending stake.
if (!pool.is_preactive()) {
pool.pending_stake = pool.pending_stake - principal.value();
};
return principal
};
let (pool_token_withdraw_amount, mut principal_withdraw) =
withdraw_from_principal(pool, staked_iota);
let principal_withdraw_amount = principal_withdraw.value();
let rewards_withdraw = withdraw_rewards(
pool, principal_withdraw_amount, pool_token_withdraw_amount, ctx.epoch()
);
let total_iota_withdraw_amount = principal_withdraw_amount + rewards_withdraw.value();
pool.pending_total_iota_withdraw = pool.pending_total_iota_withdraw + total_iota_withdraw_amount;
pool.pending_pool_token_withdraw = pool.pending_pool_token_withdraw + pool_token_withdraw_amount;
// If the pool is inactive, we immediately process the withdrawal.
if (is_inactive(pool)) process_pending_stake_withdraw(pool);
// TODO: implement withdraw bonding period here.
principal_withdraw.join(rewards_withdraw);
principal_withdraw
}

Function withdraw_from_principal

Withdraw the principal IOTA stored in the StakedIota object, and calculate the corresponding amount of pool tokens using exchange rate at staking epoch. Returns values are amount of pool tokens withdrawn and withdrawn principal portion of IOTA.

public(friend) fun withdraw_from_principal(pool: &staking_pool::StakingPoolV1, staked_iota: staking_pool::StakedIota): (u64, balance::Balance<iota::IOTA>)

Implementation

public(package) fun withdraw_from_principal(
pool: &StakingPoolV1,
staked_iota: StakedIota,
) : (u64, Balance<IOTA>) {
// Check that the stake information matches the pool.
assert!(staked_iota.pool_id == object::id(pool), EWrongPool);
let exchange_rate_at_staking_epoch = pool_token_exchange_rate_at_epoch(pool, staked_iota.stake_activation_epoch);
let principal_withdraw = unwrap_staked_iota(staked_iota);
let pool_token_withdraw_amount = get_token_amount(
&exchange_rate_at_staking_epoch,
principal_withdraw.value()
);
(
pool_token_withdraw_amount,
principal_withdraw,
)
}

Function unwrap_staked_iota

fun unwrap_staked_iota(staked_iota: staking_pool::StakedIota): balance::Balance<iota::IOTA>

Implementation

fun unwrap_staked_iota(staked_iota: StakedIota): Balance<IOTA> {
let StakedIota {
id,
pool_id: _,
stake_activation_epoch: _,
principal,
} = staked_iota;
object::delete(id);
principal
}

Function deposit_rewards

Called at epoch advancement times to add rewards (in IOTA) to the staking pool.

public(friend) fun deposit_rewards(pool: &mut staking_pool::StakingPoolV1, rewards: balance::Balance<iota::IOTA>)

Implementation

public(package) fun deposit_rewards(pool: &mut StakingPoolV1, rewards: Balance<IOTA>) {
pool.iota_balance = pool.iota_balance + rewards.value();
pool.rewards_pool.join(rewards);
}

Function process_pending_stakes_and_withdraws

public(friend) fun process_pending_stakes_and_withdraws(pool: &mut staking_pool::StakingPoolV1, ctx: &tx_context::TxContext)

Implementation

public(package) fun process_pending_stakes_and_withdraws(pool: &mut StakingPoolV1, ctx: &TxContext) {
let new_epoch = ctx.epoch() + 1;
process_pending_stake_withdraw(pool);
process_pending_stake(pool);
pool.exchange_rates.add(
new_epoch,
PoolTokenExchangeRate { iota_amount: pool.iota_balance, pool_token_amount: pool.pool_token_balance },
);
check_balance_invariants(pool, new_epoch);
}

Function process_pending_stake_withdraw

Called at epoch boundaries to process pending stake withdraws requested during the epoch. Also called immediately upon withdrawal if the pool is inactive.

fun process_pending_stake_withdraw(pool: &mut staking_pool::StakingPoolV1)

Implementation

fun process_pending_stake_withdraw(pool: &mut StakingPoolV1) {
pool.iota_balance = pool.iota_balance - pool.pending_total_iota_withdraw;
pool.pool_token_balance = pool.pool_token_balance - pool.pending_pool_token_withdraw;
pool.pending_total_iota_withdraw = 0;
pool.pending_pool_token_withdraw = 0;
}

Function process_pending_stake

Called at epoch boundaries to process the pending stake.

public(friend) fun process_pending_stake(pool: &mut staking_pool::StakingPoolV1)

Implementation

public(package) fun process_pending_stake(pool: &mut StakingPoolV1) {
// Use the most up to date exchange rate with the rewards deposited and withdraws effectuated.
let latest_exchange_rate =
PoolTokenExchangeRate { iota_amount: pool.iota_balance, pool_token_amount: pool.pool_token_balance };
pool.iota_balance = pool.iota_balance + pool.pending_stake;
pool.pool_token_balance = get_token_amount(&latest_exchange_rate, pool.iota_balance);
pool.pending_stake = 0;
}

Function withdraw_rewards

This function does the following:

1. Calculates the total amount of IOTA (including principal and rewards) that the provided pool tokens represent at the current exchange rate.
2. Using the above number and the given principal_withdraw_amount, calculates the rewards portion of the stake we should withdraw.
3. Withdraws the rewards portion from the rewards pool at the current exchange rate. We only withdraw the rewards portion because the principal portion was already taken out of the staker's self custodied StakedIota.

fun withdraw_rewards(pool: &mut staking_pool::StakingPoolV1, principal_withdraw_amount: u64, pool_token_withdraw_amount: u64, epoch: u64): balance::Balance<iota::IOTA>

Implementation

fun withdraw_rewards(
pool: &mut StakingPoolV1,
principal_withdraw_amount: u64,
pool_token_withdraw_amount: u64,
epoch: u64,
) : Balance<IOTA> {
let exchange_rate = pool_token_exchange_rate_at_epoch(pool, epoch);
let total_iota_withdraw_amount = get_iota_amount(&exchange_rate, pool_token_withdraw_amount);
let mut reward_withdraw_amount =
if (total_iota_withdraw_amount >= principal_withdraw_amount)
total_iota_withdraw_amount - principal_withdraw_amount
else 0;
// This may happen when we are withdrawing everything from the pool and
// the rewards pool balance may be less than reward_withdraw_amount.
// TODO: FIGURE OUT EXACTLY WHY THIS CAN HAPPEN.
reward_withdraw_amount = reward_withdraw_amount.min(pool.rewards_pool.value());
pool.rewards_pool.split(reward_withdraw_amount)
}

Function activate_staking_pool

Called by validator module to activate a staking pool.

public(friend) fun activate_staking_pool(pool: &mut staking_pool::StakingPoolV1, activation_epoch: u64)

Implementation

public(package) fun activate_staking_pool(pool: &mut StakingPoolV1, activation_epoch: u64) {
// Add the initial exchange rate to the table.
pool.exchange_rates.add(
activation_epoch,
initial_exchange_rate()
);
// Check that the pool is preactive and not inactive.
assert!(is_preactive(pool), EPoolAlreadyActive);
assert!(!is_inactive(pool), EActivationOfInactivePool);
// Fill in the active epoch.
pool.activation_epoch.fill(activation_epoch);
}

Function deactivate_staking_pool

Deactivate a staking pool by setting the deactivation_epoch. After this pool deactivation, the pool stops earning rewards. Only stake withdraws can be made to the pool.

public(friend) fun deactivate_staking_pool(pool: &mut staking_pool::StakingPoolV1, deactivation_epoch: u64)

Implementation

public(package) fun deactivate_staking_pool(pool: &mut StakingPoolV1, deactivation_epoch: u64) {
// We can't deactivate an already deactivated pool.
assert!(!is_inactive(pool), EDeactivationOfInactivePool);
pool.deactivation_epoch = option::some(deactivation_epoch);
}

Function iota_balance

public fun iota_balance(pool: &staking_pool::StakingPoolV1): u64

Implementation

public fun iota_balance(pool: &StakingPoolV1): u64 { pool.iota_balance }

Function pool_id

public fun pool_id(staked_iota: &staking_pool::StakedIota): object::ID

Implementation

public fun pool_id(staked_iota: &StakedIota): ID { staked_iota.pool_id }

Function staked_iota_amount

public fun staked_iota_amount(staked_iota: &staking_pool::StakedIota): u64

Implementation

public fun staked_iota_amount(staked_iota: &StakedIota): u64 { staked_iota.principal.value() }

Function stake_activation_epoch

public fun stake_activation_epoch(staked_iota: &staking_pool::StakedIota): u64

Implementation

public fun stake_activation_epoch(staked_iota: &StakedIota): u64 {
staked_iota.stake_activation_epoch
}

Function is_preactive

Returns true if the input staking pool is preactive.

public fun is_preactive(pool: &staking_pool::StakingPoolV1): bool

Implementation

public fun is_preactive(pool: &StakingPoolV1): bool{
pool.activation_epoch.is_none()
}

Function is_inactive

Returns true if the input staking pool is inactive.

public fun is_inactive(pool: &staking_pool::StakingPoolV1): bool

Implementation

public fun is_inactive(pool: &StakingPoolV1): bool {
pool.deactivation_epoch.is_some()
}

Function split

Split StakedIota self to two parts, one with principal split_amount, and the remaining principal is left in self. All the other parameters of the StakedIota like stake_activation_epoch or pool_id remain the same.

public fun split(self: &mut staking_pool::StakedIota, split_amount: u64, ctx: &mut tx_context::TxContext): staking_pool::StakedIota

Implementation

public fun split(self: &mut StakedIota, split_amount: u64, ctx: &mut TxContext): StakedIota {
let original_amount = self.principal.value();
assert!(split_amount <= original_amount, EInsufficientIotaTokenBalance);
let remaining_amount = original_amount - split_amount;
// Both resulting parts should have at least MIN_STAKING_THRESHOLD.
assert!(remaining_amount >= MIN_STAKING_THRESHOLD, EStakedIotaBelowThreshold);
assert!(split_amount >= MIN_STAKING_THRESHOLD, EStakedIotaBelowThreshold);
StakedIota {
id: object::new(ctx),
pool_id: self.pool_id,
stake_activation_epoch: self.stake_activation_epoch,
principal: self.principal.split(split_amount),
}
}

Function split_staked_iota

Split the given StakedIota to the two parts, one with principal split_amount, transfer the newly split part to the sender address.

public entry fun split_staked_iota(stake: &mut staking_pool::StakedIota, split_amount: u64, ctx: &mut tx_context::TxContext)

Implementation

public entry fun split_staked_iota(stake: &mut StakedIota, split_amount: u64, ctx: &mut TxContext) {
transfer::transfer(split(stake, split_amount, ctx), ctx.sender());
}

Function join_staked_iota

Consume the staked iota other and add its value to self. Aborts if some of the staking parameters are incompatible (pool id, stake activation epoch, etc.)

public entry fun join_staked_iota(self: &mut staking_pool::StakedIota, other: staking_pool::StakedIota)

Implementation

public entry fun join_staked_iota(self: &mut StakedIota, other: StakedIota) {
assert!(is_equal_staking_metadata(self, &other), EIncompatibleStakedIota);
let StakedIota {
id,
pool_id: _,
stake_activation_epoch: _,
principal,
} = other;
id.delete();
self.principal.join(principal);
}

Function is_equal_staking_metadata

Returns true if all the staking parameters of the staked iota except the principal are identical

public fun is_equal_staking_metadata(self: &staking_pool::StakedIota, other: &staking_pool::StakedIota): bool

Implementation

public fun is_equal_staking_metadata(self: &StakedIota, other: &StakedIota): bool {
(self.pool_id == other.pool_id) &&
(self.stake_activation_epoch == other.stake_activation_epoch)
}

Function pool_token_exchange_rate_at_epoch

public fun pool_token_exchange_rate_at_epoch(pool: &staking_pool::StakingPoolV1, epoch: u64): staking_pool::PoolTokenExchangeRate

Implementation

public fun pool_token_exchange_rate_at_epoch(pool: &StakingPoolV1, epoch: u64): PoolTokenExchangeRate {
// If the pool is preactive then the exchange rate is always 1:1.
if (is_preactive_at_epoch(pool, epoch)) {
return initial_exchange_rate()
};
let clamped_epoch = pool.deactivation_epoch.get_with_default(epoch);
let mut epoch = clamped_epoch.min(epoch);
let activation_epoch = *pool.activation_epoch.borrow();
// Find the latest epoch that's earlier than the given epoch with an entry in the table
while (epoch >= activation_epoch) {
if (pool.exchange_rates.contains(epoch)) {
return pool.exchange_rates[epoch]
};
epoch = epoch - 1;
};
// This line really should be unreachable. Do we want an assert false here?
initial_exchange_rate()
}

Function pending_stake_amount

Returns the total value of the pending staking requests for this staking pool.

public fun pending_stake_amount(staking_pool: &staking_pool::StakingPoolV1): u64

Implementation

public fun pending_stake_amount(staking_pool: &StakingPoolV1): u64 {
staking_pool.pending_stake
}

Function pending_stake_withdraw_amount

Returns the total withdrawal from the staking pool this epoch.

public fun pending_stake_withdraw_amount(staking_pool: &staking_pool::StakingPoolV1): u64

Implementation

public fun pending_stake_withdraw_amount(staking_pool: &StakingPoolV1): u64 {
staking_pool.pending_total_iota_withdraw
}

Function exchange_rates

public(friend) fun exchange_rates(pool: &staking_pool::StakingPoolV1): &table::Table<u64, staking_pool::PoolTokenExchangeRate>

Implementation

public(package) fun exchange_rates(pool: &StakingPoolV1): &Table<u64, PoolTokenExchangeRate> {
&pool.exchange_rates
}

Function iota_amount

public fun iota_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate): u64

Implementation

public fun iota_amount(exchange_rate: &PoolTokenExchangeRate): u64 {
exchange_rate.iota_amount
}

Function pool_token_amount

public fun pool_token_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate): u64

Implementation

public fun pool_token_amount(exchange_rate: &PoolTokenExchangeRate): u64 {
exchange_rate.pool_token_amount
}

Function is_preactive_at_epoch

Returns true if the provided staking pool is preactive at the provided epoch.

fun is_preactive_at_epoch(pool: &staking_pool::StakingPoolV1, epoch: u64): bool

Implementation

fun is_preactive_at_epoch(pool: &StakingPoolV1, epoch: u64): bool{
// Either the pool is currently preactive or the pool's starting epoch is later than the provided epoch.
is_preactive(pool) || (*pool.activation_epoch.borrow() > epoch)
}

Function get_iota_amount

fun get_iota_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate, token_amount: u64): u64

Implementation

fun get_iota_amount(exchange_rate: &PoolTokenExchangeRate, token_amount: u64): u64 {
// When either amount is 0, that means we have no stakes with this pool.
// The other amount might be non-zero when there's dust left in the pool.
if (exchange_rate.iota_amount == 0 || exchange_rate.pool_token_amount == 0) {
return token_amount
};
let res = exchange_rate.iota_amount as u128

(token_amount as u128)
/ (exchange_rate.pool_token_amount as u128);
res as u64
}

Function get_token_amount

fun get_token_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate, iota_amount: u64): u64

Implementation

fun get_token_amount(exchange_rate: &PoolTokenExchangeRate, iota_amount: u64): u64 {
// When either amount is 0, that means we have no stakes with this pool.
// The other amount might be non-zero when there's dust left in the pool.
if (exchange_rate.iota_amount == 0 || exchange_rate.pool_token_amount == 0) {
return iota_amount
};
let res = exchange_rate.pool_token_amount as u128

(iota_amount as u128)
/ (exchange_rate.iota_amount as u128);
res as u64
}

Function initial_exchange_rate

fun initial_exchange_rate(): staking_pool::PoolTokenExchangeRate

Implementation

fun initial_exchange_rate(): PoolTokenExchangeRate {
PoolTokenExchangeRate { iota_amount: 0, pool_token_amount: 0 }
}

Function check_balance_invariants

fun check_balance_invariants(pool: &staking_pool::StakingPoolV1, epoch: u64)

Implementation

fun check_balance_invariants(pool: &StakingPoolV1, epoch: u64) {
let exchange_rate = pool_token_exchange_rate_at_epoch(pool, epoch);
// check that the pool token balance and iota balance ratio matches the exchange rate stored.
let expected = get_token_amount(&exchange_rate, pool.iota_balance);
let actual = pool.pool_token_balance;
assert!(expected == actual, ETokenBalancesDoNotMatchExchangeRate)
}