# Contract Details The NativePool contract relies on several core objects to manage staking, unstaking, and validator selection efficiently. Below is an overview of the key components: ### **Main Objects** * `OwnerCap`: Grants the capability to call functions restricted to the **Owner** role. * `OperatorCap`: Grants the capability to call functions restricted to the **Operator** role. * `Vault`: Stores the staking queue for a specific validator. During unstaking, funds are released following a First-In-First-Out (FIFO) approach. * `ValidatorSet`: Stores a priority-sorted list of validators, each associated with a `Vault` for efficient staking and unstaking operations. * `NativePool`: The central staking pool that holds the `ValidatorSet` and manages all key staking-related data. * `Metadata`: Tracks the total supply of stIOTA tokens, which represent liquid staking assets within the IOTA ecosystem. ### **Dependencies** Some methods in the NativePool contract rely on IOTA system objects to function properly. The key dependency is: * `IotaSystemState`: Provides real-time data on the current state of the IOTA network, ensuring staking and unstaking operations are executed based on the latest network conditions. ### Staking Process Users interact with the NativePool contract through the following staking function: ``` stake( self: &mut NativePool, metadata: &mut Metadata, wrapper: &mut IotaSystemState, coin: Coin, ctx: &mut TxContext ); ``` **How it works** * **IOTA to stIOTA Conversion**: Users stake IOTA tokens in exchange for stIOTA tokens. * **Pending Balance Management**: The staked IOTA is added to the pending balance. If the pending amount exceeds `1 IOTA`, the contract proceeds with staking. * **Validator Selection**: The system stakes tokens with the highest-priority validator; otherwise, the tokens remain in the pool. * **Reward Accrual**: * Users immediately start earning rewards upon staking. * However, the staked amount itself begins accruing rewards from the next epoch. ### Unstaking Process The NativePool contract supports an instant unstake mechanism. The unstaking function is defined as follows: ``` unstake( self: &mut NativePool, wrapper: &mut IotaSystemState, metadata: &mut Metadata, cert: Coin, ctx: &mut TxContext ); ``` **How it works** * **Instant Unstake Mechanism**: * Burns stIOTA tokens and immediately returns the equivalent amount in IOTA. * **Validator Withdrawal**: * Calls `unstake_amount_from_validators` to retrieve IOTA from validators. This ensures a fast exit mechanism, allowing users to redeem their staked IOTA without waiting for epoch transitions. ### Rewards Calculation After an epoch change, the backend queries the total accrued rewards for all StakedIota and updates the contract accordingly. **Reward Ratio Update Formula** The staking ratio is recalculated using the following formula: `shares_supply / (total_staked + (total_rewards − collected_rewards))` Where: * `shares_supply`: Total supply of stIOTA tokens. * `total_staked`: Last recorded amount of staked IOTA. * `total_rewards`: Cumulative staking rewards recorded in the contract. * `collected_rewards`: Rewards that have already been withdrawn. ### Ratio Management The NativePool contract provides functions to manage and retrieve the stIOTA-to-IOTA conversion ratio. These functions allow users to convert between IOTA and stIOTA tokens based on the latest staking ratio. * Returns the current stIOTA-to-IOTA ratio: `get_ratio(self: &NativePool, metadata: &Metadata) -> u256` * Converts a given IOTA amount into stIOTA tokens using the current ratio: `to_shares(self: &NativePool, metadata: &Metadata, amount: u64) -> u64` * Converts a given stIOTA token amount back into IOTA using the current ratio: `from_shares(self: &NativePool, metadata: &Metadata, shares: u64) -> u64` These functions ensure accurate conversions between IOTA and stIOTA while maintaining a dynamically updated staking ratio. ### Validator Management The NativePool contract dynamically adjusts validator priorities to optimize staking performance and decentralization. The prioritization is based on the following factors: * **APY Performance**: Validators offering higher yields are favored. * **Reputation**: Validators with a strong and reliable track record receive higher priority. * **Staking Distribution**: Validators holding more than 20% of the total value locked (TVL) are deprioritized to prevent centralization risks. #### Staking and Unstaking Strategy * **Staking**: The contract stakes with the highest-priority validator. * **Unstaking**: The contract unstakes from the lowest-priority validator first. #### Function: Dynamic Validator Update By continuously optimizing validator selection, the contract enhances staking efficiency. ``` update_validators(NativePool, vector
, vector, OperatorCap) ``` * Dynamically re-prioritizes validators based on updated performance metrics. * Ensures stake distribution remains optimal and prevents overconcentration of funds in a single validator. ### Fee Management The NativePool contract collects and transfers fees to maintain the stability and efficiency of the protocol. #### Function: Collect Fees This mechanism ensures that staking and unstaking operations remain efficient and sustainable, while collected fees are distributed appropriately within the network. ``` collect_fee( self: &mut NativePool, to: address, ctx: &mut TxContext ); ``` * Transfers collected fees to a designated address. * Emits a `FeeCollectedEvent` with the amount transferred, ensuring transparency in fee distribution. ### Pause Functionality The NativePool contract includes a pause mechanism that allows the contract owner to temporarily halt staking and unstaking operations. #### Function: Set Pause Status This function is useful for security measures, upgrades, or emergency responses, allowing administrators to temporarily disable interactions with the staking pool if needed. ``` set_pause( self: &mut NativePool, _owner_cap: &OwnerCap, val: bool ); ``` * Toggles the pool's pause status On/Off based on the provided `val` parameter (`true` to pause, `false` to resume). * Emits a `PausedEvent` to log the new status. ### Migration & Upgrades The NativePool contract includes mechanisms for version upgrades to ensure compatibility and maintain protocol integrity over time. The functions enable seamless upgrades, ensuring the contract remains secure, maintainable, and up-to-date without disrupting staking operations. #### Function: Contract Migration ``` migrate( self: &mut NativePool, _owner_cap: &OwnerCap ); ``` * Updates the contract version to a new release. * Emits a `MigratedEvent`, recording the new version. #### Function: Version Assertion ``` assert_version(self: &NativePool); ``` * Ensures that contract interactions only occur with a compatible version. * Prevents users from engaging with outdated or deprecated contract versions. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.swirlstake.com/tech/iota-contract-infrastructure/contract-details.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.