Struct WhitelistMapper 

pub struct WhitelistMapper<SA, T, A = CurrentStorage>
where
    SA: StorageMapperApi,
    A: StorageAddress<SA>,
    T: NestedEncode + 'static,
{ /* private fields */ }

A non-iterable whitelist mapper optimized for fast membership testing.

Storage Layout

The WhitelistMapper uses a simple direct key approach with boolean flags:

• base_key + encoded_item → true (if whitelisted) or empty (if not whitelisted)

Each whitelisted item requires exactly one storage key, making this extremely space-efficient. Uses SingleValueMapper<bool> internally for each item.

Main Operations

• Add: add(item) - Adds item to whitelist. O(1) with one storage write.
• Remove: remove(item) - Removes item from whitelist. O(1) with storage clear.
• Check: contains(item) - Tests membership. O(1) with one storage read.
• Require: require_whitelisted(item) - Checks membership or errors. O(1).

Key Characteristics

• Non-iterable: Cannot iterate over whitelisted items (use SetMapper if iteration needed)
• Space-efficient: One storage key per item, minimal overhead
• Fast lookups: Direct key-based membership testing
• Boolean logic: Uses presence/absence, since true = 1, false = empty

Trade-offs

• Pros: Extremely efficient for membership testing; minimal storage overhead; simple and fast.
• Cons: No iteration capability; no built-in counting; cannot list all whitelisted items; no bulk operations.

Comparison with SetMapper/UnorderedSetMapper

• WhitelistMapper: Non-iterable; most space-efficient; fastest lookups
• SetMapper: Iterable; maintains insertion order; higher overhead
• UnorderedSetMapper: Iterable; no order guarantees; moderate overhead

Use Cases

• Simple whitelists where iteration is not needed
• Permission systems (allowed addresses, tokens, etc.)
• Feature flags or capability checking
• Any membership testing where space efficiency is critical
• Large whitelists where iteration would be prohibitively expensive

Example

// Add addresses to whitelist
whitelist.add(&admin);
whitelist.add(&user1);

// Check membership
assert!(whitelist.contains(&admin));
assert!(whitelist.contains(&user1));
assert!(!whitelist.contains(&user2));

// Require membership (errors if not whitelisted)
whitelist.require_whitelisted(&admin);  // OK
// whitelist.require_whitelisted(&user2);  // Would error: "Item not whitelisted"

// Remove from whitelist
whitelist.remove(&user1);
assert!(!whitelist.contains(&user1));

// Use in access control
fn admin_only_function<SA: multiversx_sc::api::StorageMapperApi>(
    whitelist: &WhitelistMapper<SA, ManagedAddress<SA>>,
    caller: &ManagedAddress<SA>
) {
    whitelist.require_whitelisted(caller);
    // Function logic here...
}

Token Whitelist Example

// Whitelist specific tokens
allowed_tokens.add(&token1);

// Validate token in payment
if allowed_tokens.contains(&token1) {
    // Process payment
} else {
    // Reject payment
}

Implementations

impl<SA, T> WhitelistMapper<SA, T, ManagedAddress<SA>>

where SA: StorageMapperApi, T: TopDecode + TopEncode + NestedEncode + 'static,

pub fn contains(&self, item: &T) -> bool

pub fn require_whitelisted(&self, item: &T)

impl<SA, T> WhitelistMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopDecode + TopEncode + NestedEncode + 'static,

pub fn contains(&self, item: &T) -> bool

pub fn require_whitelisted(&self, item: &T)

pub fn add(&self, item: &T)

pub fn remove(&self, item: &T)

Trait Implementations

impl<SA, T> StorageMapper<SA> for WhitelistMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: NestedEncode + 'static,

fn new(base_key: StorageKey<SA>) -> Self

Will be called automatically by the #[storage_mapper] annotation generated code.

impl<SA, T> StorageMapperFromAddress<SA> for WhitelistMapper<SA, T, ManagedAddress<SA>>

where SA: StorageMapperApi, T: NestedEncode + 'static,

fn new_from_address( address: ManagedAddress<SA>, base_key: StorageKey<SA>, ) -> Self

Will be called automatically by the #[storage_mapper_from_address] annotation generated code.