Rust区块链开发库pallet-staking-runtime-api的使用

概述

pallet-staking-runtime-api是Substrate框架中用于质押(staking)和验证人功能的核心运行时API。它为区块链提供了基本的质押机制，允许用户参与网络共识并获得奖励，同时支持验证人选举和管理功能。

主要功能

1. 质押代币参与网络共识
2. 验证人选举和奖励分配
3. 提名验证人
4. 解绑和提取质押资金
5. 验证人评分和惩罚(slashing)

使用方法

1. 添加依赖

首先需要在项目的Cargo.toml中添加依赖：

[dependencies]
pallet-staking-runtime-api = { git = "https://github.com/paritytech/substrate.git", branch = "master" }
sp-api = { git = "https://github.com/paritytech/substrate.git", branch = "master" }

2. 实现Runtime API

在你的runtime中实现staking API trait：

use pallet_staking_runtime_api::{StakingApi, Nominations};

impl StakingApi<Block> for Runtime {
    fn active_era() -> sp_staking::EraIndex {
        Staking::active_era().index
    }
    
    fn current_era() -> sp_staking::EraIndex {
        Staking::current_era()
    }
    
    fn nominations(who: &AccountId) -> Option<Nominations<AccountId>> {
        Staking::nominations(who)
    }
}

3. 基本质押操作示例

质押代币

use frame_support::dispatch::DispatchResult;

fn stake(controller: &AccountId, value: Balance) -> DispatchResult {
    Staking::bond(Origin::signed(controller.clone()), controller.clone(), value, RewardDestination::Staked)
}

提名验证人

fn nominate(nominator: &AccountId, validators: Vec<AccountId>) -> DispatchResult {
    Staking::nominate(Origin::signed(nominator.clone()), validators)
}

解绑资金

fn unbond(staker: &AccountId, value: Balance) -> DispatchResult {
    Staking::unbond(Origin::signed(staker.clone()), value)
}

4. 查询质押信息

获取当前era

let current_era = Staking::current_era();

获取验证人信息

use pallet_staking::Exposure;

fn get_validator_exposure(era: EraIndex, validator: &AccountId) -> Option<Exposure<AccountId, Balance>> {
    Staking::eras_stakers(era, validator)
}

5. 验证人操作

设置验证人佣金

fn set_validator_commission(validator: &AccountId, commission: Perbill) -> DispatchResult {
    Staking::validate(Origin::signed(validator.clone()), ValidatorPrefs { commission })
}

领取奖励

fn claim_rewards(staker: &AccountId, era: EraIndex) -> DispatchResult {
    Staking::payout_stakers(Origin::signed(staker.clone()), validator.clone(), era)
}

高级功能

自定义奖励计算

impl pallet_staking::Config for Runtime {
    type EraRewardCalculator = CustomEraReward;
}

struct CustomEraReward;

impl EraRewardCalculator<Balance> for CustomEraReward {
    fn calculate_reward(
        total_staked: Balance,
        total_issuance: Balance,
        _era_duration_millis: u64,
    ) -> (Balance, Balance) {
        // 自定义奖励计算逻辑
        let reward = total_staked / 100; // 1%奖励
        (reward, reward)
    }
}

自定义slash处理

impl pallet_staking::Config for Runtime {
    type SlashHandler = CustomSlashHandler;
}

struct CustomSlashHandler;

impl SlashHandler<AccountId, Balance> for CustomSlashHandler {
    fn on_slash(
        validator: &AccountId,
        slash: Balance,
        _current_era: EraIndex,
        _active_era: EraIndex,
    ) {
        // 自定义slash处理逻辑
        log::info!("Validator {} slashed by {}", validator, slash);
    }
}

完整示例demo

下面是一个完整的质押系统实现示例，整合了上述所有功能：

//! 完整质押系统示例

use frame_support::{dispatch::DispatchResult, traits::Currency};
use frame_system::Config as SystemConfig;
use pallet_staking::{
    Config as StakingConfig, Exposure, Nominations, RewardDestination, ValidatorPrefs,
};
use sp_runtime::{
    traits::{Block as BlockT, StaticLookup},
    Perbill,
};
use sp_staking::EraIndex;

/// 质押系统实现
pub struct StakingSystem<T: StakingConfig + SystemConfig> {
    _marker: std::marker::PhantomData<T>,
}

impl<T: StakingConfig + SystemConfig> StakingSystem<T> {
    /// 质押代币
    pub fn bond(
        controller: &T::AccountId,
        value: <T as StakingConfig>::CurrencyBalance,
    ) -> DispatchResult {
        // 质押代币并设置奖励目标为继续质押
        pallet_staking::Pallet::<T>::bond(
            RawOrigin::Signed(controller.clone()).into(),
            controller.clone(),
            value,
            RewardDestination::Staked,
        )
    }

    /// 提名验证人
    pub fn nominate(
        nominator: &T::AccountId,
        validators: Vec<<T as SystemConfig>::AccountId>,
    ) -> DispatchResult {
        pallet_staking::Pallet::<T>::nominate(
            RawOrigin::Signed(nominator.clone()).into(),
            validators,
        )
    }

    /// 解绑质押资金
    pub fn unbond(
        staker: &T::AccountId,
        value: <T as StakingConfig>::CurrencyBalance,
    ) -> DispatchResult {
        pallet_staking::Pallet::<T>::unbond(
            RawOrigin::Signed(staker.clone()).into(), 
            value
        )
    }

    /// 获取当前era
    pub fn current_era() -> EraIndex {
        pallet_staking::Pallet::<T>::current_era()
    }

    /// 获取验证人信息
    pub fn validator_exposure(
        era: EraIndex,
        validator: &T::AccountId,
    ) -> Option<Exposure<T::AccountId, <T as StakingConfig>::CurrencyBalance>> {
        pallet_staking::Pallet::<T>::eras_stakers(era, validator)
    }

    /// 设置验证人佣金
    pub fn set_validator_commission(
        validator: &T::AccountId,
        commission: Perbill,
    ) -> DispatchResult {
        pallet_staking::Pallet::<T>::validate(
            RawOrigin::Signed(validator.clone()).into(),
            ValidatorPrefs { commission, ..Default::default() },
        )
    }

    /// 领取奖励
    pub fn claim_rewards(
        staker: &T::AccountId,
        validator: &T::AccountId,
        era: EraIndex,
    ) -> DispatchResult {
        pallet_staking::Pallet::<T>::payout_stakers(
            RawOrigin::Signed(staker.clone()).into(),
            validator.clone(),
            era,
        )
    }
}

/// 自定义奖励计算器
pub struct CustomRewardCalculator;

impl pallet_staking::EraRewardCalculator<<T as StakingConfig>::CurrencyBalance>
    for CustomRewardCalculator
{
    fn calculate_reward(
        total_staked: <T as StakingConfig>::CurrencyBalance,
        total_issuance: <T as StakingConfig>::CurrencyBalance,
        _era_duration_millis: u64,
    ) -> (<T as StakingConfig>::CurrencyBalance, <T as StakingConfig>::CurrencyBalance) {
        // 更复杂的奖励计算逻辑
        let reward = total_staked / 50; // 2%奖励
        (reward, reward)
    }
}

/// 自定义slash处理器
pub struct CustomSlashHandler;

impl pallet_staking::SlashHandler<T::AccountId, <T as StakingConfig>::CurrencyBalance>
    for CustomSlashHandler
{
    fn on_slash(
        validator: &T::AccountId,
        slash: <T as StakingConfig>::CurrencyBalance,
        _current_era: EraIndex,
        _active_era: EraIndex,
    ) {
        // 更复杂的slash处理逻辑
        log::warn!(
            "Validator {} was slashed by {} tokens",
            validator,
            slash
        );
        // 可以在这里添加额外的惩罚逻辑
    }
}

注意事项

1. 质押操作通常有锁定期，资金不能立即提取
2. 验证人需要满足最低质押要求
3. 提名多个验证人时，资金会自动分配到最需要的验证人
4. 不活跃或行为不当的验证人可能会受到slash惩罚

通过pallet-staking-runtime-api，开发者可以构建复杂的质押经济系统，为PoS区块链提供核心的安全和共识机制。