Staking Related Modules

Overview

The provided examples illustrate a series of Move modules focused on staking functionality within Initia. These modules enable users to register for staking, delegate and undelegate tokens, claim rewards, and obtain information about their staking activities and unbonding processes. Here's a breakdown of the functionality provided by each entry and view function within the staking module context:

Entry Functions

Register an Account Delegation Store

Initializes a storage area for an account's delegation activities, allowing it to participate in staking operations.

public entry fun register(
    account: &signer // account to register
){
    ...
}

Delegate Coin and Deposit Rewards

Allows an account to delegate tokens to a validator. This process involves specifying the token type through metadata, the validator's address, and the amount to be delegated.

public entry fun delegate_script(
    account: &signer,
    metadata: Object<Metadata>, // metadata of the coin/lp token to delegate
    validator: String, // validator address in bech32 format
    amount: u64, // amount to delegate
) acquires DelegationStore, ModuleStore {
    ...
}

Undelegate

Enables the withdrawal of a previously delegated amount from a validator. Note that the returned amount might slightly vary due to rounding errors.

public entry fun undelegate_script(
    account: &signer,
    metadata: Object<Metadata>, // metadata of the coin/lp token to undelegate
    validator: String, // validator address in bech32 format
    amount: u64, // amount to delegate
) acquires DelegationStore, ModuleStore {
		...
}

Claim unbonding_coin from Expired Unbonding

Permits the claiming of tokens after the unbonding period has expired, based on the specified metadata, validator, and release time.

public entry fun claim_unbonding_script(
    account: &signer,
    metadata: Object<Metadata>, // metadata of the coin/lp token to claim
    validator: String, // validator address in bech32 format
    release_time: u64 // release timstamp of unbonding in seconds
) acquires DelegationStore, ModuleStore {
		...
}

Claim Rewards

Allows an account to claim staking rewards from a specific validator, based on the tokens delegated.

public entry fun claim_reward_script(
    account: &signer,
    metadata: Object<Metadata>, // metadata of the coin/lp token that you delegated
    validator: String // validator address in bech32 format
) acquires DelegationStore, ModuleStore {
    ...
}

View Functions

Get Delegation Info of an Address and a Validator Address

Retrieves detailed information about a specific delegation, including the metadata of the delegated tokens, the validator involved, and the response details like share and unclaimed rewards.

public fun get_delegation(
    addr: address, // address who delegated
    metadata: Object<Metadata>, // metadata of the coin/lp token that address delegated
    validator: String, // validator address in bech32 format
): DelegationResponse acquires DelegationStore, ModuleStore {
    ...
}

Get All Delegation Info of an Address

Fetches all delegation records for a given address, with the ability to paginate results using a start_after validator address and limit the number of responses.

public fun get_delegations(
    addr: address, // address who delegated
    metadata: Object<Metadata>, // metadata of the coin/lp token that address delegated
    start_after: Option<String>, // validator address offset of query
    limit: u8, // number of response (MAX = 30)
): vector<DelegationResponse> acquires DelegationStore, ModuleStore {
		...
}

Example Response of get_delegation and get_delegations

Contains information returned by the delegation queries, including details about the delegation share, unclaimed rewards, and the tokens involved.

struct DelegationResponse has drop {
    metadata: Object<Metadata>, // metadata of the coin/lp token that address delegated
    validator: String, // validator address in bech32 format
    share: u64, // share of delegation 
    unclaimed_reward: u64, // unclaimed init reward
}

Get Unbonding Info

Obtains information about a specific unbonding operation, detailing the metadata, validator, release time, and other relevant data.

public fun get_unbonding(
    addr: address, // address who undelegated
    metadata: Object<Metadata>, // metadata of the coin/lp token that address undelegated
    validator: String, // validator address in bech32 format
    release_time: u64, // release timstamp of unbonding in seconds
): UnbondingResponse acquires DelegationStore, ModuleStore {
    ...
}

Get All Unbondings of an Address

Retrieves all unbonding records for a specific address and validator, offering pagination through start_after_validator and start_after_release_time, alongside a response limit.

public fun get_unbondings(
    addr: address, // address who undelegated
    metadata: Object<Metadata>, // metadata of the coin/lp token that address undelegated
    start_after_validator: Option<String>, // validator address offset of query must be given with `start_after_release_time`
    start_after_release_time: Option<u64>, // release timestamp offset of query must be given with `start_after_validator`
    limit: u8, // number of response (MAX = 30)
): vector<UnbondingResponse> acquires DelegationStore, ModuleStore {
		...
}

Example Response of get_unbondings

Provides details from unbonding queries, such as the amount being unbonded, the associated release time, and other pertinent data.

struct UnbondingResponse has drop {
    metadata: Object<Metadata>, // metadata of the coin/lp token that address undelegated
    validator: String, // validator address in bech32 format
    unbonding_amount: u64, // unbonding amount of coin/lp token
    release_time: u64, // release timstamp of unbonding in seconds
}