Rust Substrate框架的pallet-whitelist插件使用指南

概述

pallet-whitelist是Substrate区块链框架中的一个模块，用于实现高效的链上地址白名单管理功能。这个pallet允许区块链维护一个特权地址列表，这些地址可以访问特定的链上功能或资源。

主要功能

• 添加/移除地址到白名单
• 检查地址是否在白名单中
• 白名单容量管理
• 权限控制(通常需要管理员权限操作)

使用方法

1. 引入pallet到runtime

首先需要在runtime中引入这个pallet：

// runtime/src/lib.rs

impl pallet_whitelist::Config for Runtime {
    type Event = Event;
    type WeightInfo = ();
    type WhitelistOrigin = frame_system::EnsureRoot<AccountId>;
}

construct_runtime!(
    pub enum Runtime where
        Block = Block,
        NodeBlock = opaque::Block,
        UncheckedExtrinsic = UncheckedExtrinsic
    {
        // ... 其他pallet
        Whitelist: pallet_whitelist::{Pallet, Call, Storage, Event<T>},
    }
);

2. 基本操作示例

添加地址到白名单

use frame_support::sp_runtime::AccountId32;
use hex_literal::hex;

let alice = AccountId32::new(hex!["d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d"]);
Whitelist::add_to_whitelist(RuntimeOrigin::root(), alice.clone()).unwrap();

从白名单移除地址

Whitelist::remove_from_whitelist(RuntimeOrigin::root(), alice.clone()).unwrap();

检查地址是否在白名单中

let is_whitelisted = Whitelist::is_whitelisted(&alice);
println!("Is Alice whitelisted? {}", is_whitelisted);

3. 在自己的pallet中使用白名单

你可以在自定义pallet中集成白名单功能：

// 在你的pallet中引入依赖
use pallet_whitelist::Pallet as Whitelist;

#[pallet::call]
impl<T: Config> Pallet<T> {
    #[pallet::weight(10_000)]
    pub fn privileged_action(origin: OriginFor<T>) -> DispatchResult {
        let sender = ensure_signed(origin)?;
        
        // 检查调用者是否在白名单中
        ensure!(Whitelist::<T>::is_whitelisted(&sender), Error::<T>::NotWhitelisted);
        
        // 执行特权操作
        // ...
        
        Ok(())
    }
}

高级配置

设置白名单大小限制

// 在pallet的config trait中
pub trait Config: frame_system::Config {
    // ... 其他配置
    #[pallet::constant]
    type MaxWhitelisted: Get<u32>;
}

// runtime实现
parameter_types! {
    pub const MaxWhitelisted: u32 = 1000;
}

impl pallet_whitelist::Config for Runtime {
    // ... 其他配置
    type MaxWhitelisted = MaxWhitelisted;
}

自定义权限控制

可以修改WhitelistOrigin来指定哪些账户可以管理白名单：

impl pallet_whitelist::Config for Runtime {
    // 使用技术委员会集体控制
    type WhitelistOrigin = pallet_collective::EnsureProportionAtLeast<AccountId, TechnicalCollective, 3, 5>;
}

完整示例demo

下面是一个完整的自定义pallet示例，展示了如何集成白名单功能：

// my_pallet/src/lib.rs

#![cfg_attr(not(feature = "std"), no_std)]

pub use pallet::*;

#[frame_support::pallet]
pub mod pallet {
    use frame_support::pallet_prelude::*;
    use frame_system::pallet_prelude::*;
    use pallet_whitelist::Pallet as Whitelist;

    #[pallet::pallet]
    #[pallet::generate_store(pub(super) trait Store)]
    pub struct Pallet<T>(_);

    #[pallet::config]
    pub trait Config: frame_system::Config + pallet_whitelist::Config {
        type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;
    }

    #[pallet::event]
    #[pallet::generate_deposit(pub(super) fn deposit_event)]
    pub enum Event<T: Config> {
        PrivilegedActionExecuted(T::AccountId),
    }

    #[pallet::error]
    pub enum Error<T> {
        NotWhitelisted,
    }

    #[pallet::call]
    impl<T: Config> Pallet<T> {
        #[pallet::weight(10_000)]
        pub fn privileged_action(origin: OriginFor<T>) -> DispatchResult {
            let sender = ensure_signed(origin)?;
            
            // 检查调用者是否在白名单中
            ensure!(Whitelist::<T>::is_whitelisted(&sender), Error::<T>::NotWhitelisted);
            
            // 执行特权操作
            Self::deposit_event(Event::PrivilegedActionExecuted(sender.clone()));
            
            Ok(())
        }
    }
}

最佳实践

1. 合理设置白名单大小：根据实际需求限制白名单容量，防止滥用
2. 定期审核：建立链下流程定期审核白名单成员
3. 多层权限：对于关键操作，考虑结合其他权限控制机制
4. 事件通知：监听白名单变更事件，建立相应的通知机制

注意事项

• 白名单操作通常需要较高的交易费用
• 频繁的白名单更新可能影响链性能
• 在生产环境中应仔细设计权限控制策略