Struct AssetListBase

pub struct AssetListBase<T: AddressLike>(/* private fields */);

Represents a list of fungible tokens, each with a known amount

Implementations

impl AssetListBase<String>

pub fn check( &self, api: &dyn Api, optional_whitelist: Option<&[&str]>, ) -> Result<AssetList, AssetError>

Validate data contained in an unchecked asset list instance, return a new checked asset list instance:

• For CW20 tokens, assert the contract address is valid
• For SDK coins, assert that the denom is included in a given whitelist; skip if the whitelist is not provided

use cosmwasm_std::{Addr, Api, StdResult};
use cw_asset::{Asset, AssetList, AssetListUnchecked, AssetUnchecked};

fn validate_assets(api: &dyn Api, list_unchecked: &AssetListUnchecked) {
    match list_unchecked.check(api, Some(&["uatom", "uluna"])) {
        Ok(list) => println!("asset list is valid: {}", list.to_string()),
        Err(err) => println!("asset list is invalid! reason: {}", err),
    }
}

impl AssetListBase<Addr>

pub fn new() -> Self

Create a new, empty asset list

use cw_asset::AssetList;

let list = AssetList::new();
let len = list.len(); // should be zero

pub fn to_vec(&self) -> Vec<Asset>

Return a copy of the underlying vector

use cw_asset::{Asset, AssetList};

let list =
    AssetList::from(vec![Asset::native("uluna", 12345u128), Asset::native("uusd", 67890u128)]);

let vec: Vec<Asset> = list.to_vec();

pub fn len(&self) -> usize

Return length of the asset list

use cw_asset::{Asset, AssetList};

let list =
    AssetList::from(vec![Asset::native("uluna", 12345u128), Asset::native("uusd", 67890u128)]);

let len = list.len(); // should be two

pub fn is_empty(&self) -> bool

Return whether the asset list is empty

use cw_asset::{Asset, AssetList};

let mut list = AssetList::from(vec![Asset::native("uluna", 12345u128)]);
let is_empty = list.is_empty(); // should be `false`

list.deduct(&Asset::native("uluna", 12345u128)).unwrap();
let is_empty = list.is_empty(); // should be `true`

pub fn find(&self, info: &AssetInfo) -> Option<&Asset>

Find an asset in the list that matches the provided asset info

Return Some(&asset) if found, where &asset is a reference to the asset found; None if not found.

A case where is method is useful is to find how much asset the user sent along with a message:

use cosmwasm_std::MessageInfo;
use cw_asset::{AssetInfo, AssetList};

fn find_uusd_received_amount(info: &MessageInfo) {
    let list = AssetList::from(&info.funds);
    match list.find(&AssetInfo::native("uusd")) {
        Some(asset) => println!("received {} uusd", asset.amount),
        None => println!("did not receive any uusd"),
    }
}

pub fn apply<F: FnMut(&mut Asset)>(&mut self, f: F) -> &mut Self

Apply a mutation on each of the asset

An example case where this is useful is to scale the amount of each asset in the list by a certain factor:

use cw_asset::{Asset, AssetInfo, AssetList};

let mut list =
    AssetList::from(vec![Asset::native("uluna", 12345u128), Asset::native("uusd", 67890u128)]);

let list_halved = list.apply(|a| a.amount = a.amount.multiply_ratio(1u128, 2u128));

pub fn purge(&mut self) -> &mut Self

Removes all assets in the list that has zero amount

use cw_asset::{Asset, AssetList};

let mut list =
    AssetList::from(vec![Asset::native("uluna", 12345u128), Asset::native("uusd", 0u128)]);
let mut len = list.len(); // should be two

list.purge();
len = list.len(); // should be one

pub fn add(&mut self, asset_to_add: &Asset) -> Result<&mut Self, AssetError>

Add a new asset to the list

If asset of the same kind already exists in the list, then increment its amount; if not, append to the end of the list.

NOTE: purge is automatically performed following the addition, so adding an asset with zero amount has no effect.

use cw_asset::{Asset, AssetInfo, AssetList};

let mut list = AssetList::from(vec![
    Asset::native("uluna", 12345u128),
]);

list.add(&Asset::native("uusd", 67890u128));
let mut len = list.len();  // should be two

list.add(&Asset::native("uluna", 11111u128));
len = list.len();  // should still be two

let uluna_amount = list
    .find(&AssetInfo::native("uluna"))
    .unwrap()
    .amount;  // should have increased to 23456

pub fn add_many( &mut self, assets_to_add: &AssetList, ) -> Result<&mut Self, AssetError>

Add multiple new assets to the list

use cw_asset::{Asset, AssetInfo, AssetList};

let mut list = AssetList::from(vec![
    Asset::native("uluna", 12345u128),
]);

list.add_many(&AssetList::from(vec![
    Asset::native("uusd", 67890u128),
    Asset::native("uluna", 11111u128),
]));

let uusd_amount = list
    .find(&AssetInfo::native("uusd"))
    .unwrap()
    .amount;  // should be 67890

let uluna_amount = list
    .find(&AssetInfo::native("uluna"))
    .unwrap()
    .amount;  // should have increased to 23456

pub fn deduct( &mut self, asset_to_deduct: &Asset, ) -> Result<&mut Self, AssetError>

Deduct an asset from the list

The asset of the same kind and equal or greater amount must already exist in the list. If so, deduct the amount from the asset; ifnot, throw an error.

NOTE: purge is automatically performed following the addition. Therefore, if an asset’s amount is reduced to zero, it will be removed from the list.

use cw_asset::{Asset, AssetInfo, AssetList};

let mut list = AssetList::from(vec![
    Asset::native("uluna", 12345u128),
]);

list.deduct(&Asset::native("uluna", 10000u128)).unwrap();

let uluna_amount = list
    .find(&AssetInfo::native("uluna"))
    .unwrap()
    .amount;  // should have reduced to 2345

list.deduct(&Asset::native("uluna", 2345u128));

let len = list.len();  // should be zero, as uluna is purged from the list

pub fn deduct_many( &mut self, assets_to_deduct: &AssetList, ) -> Result<&mut Self, AssetError>

Deduct multiple assets from the list

use cw_asset::{Asset, AssetInfo, AssetList};

let mut list = AssetList::from(vec![
    Asset::native("uluna", 12345u128),
    Asset::native("uusd", 67890u128),
]);

list.deduct_many(&AssetList::from(vec![
    Asset::native("uluna", 2345u128),
    Asset::native("uusd", 67890u128),
])).unwrap();

let uluna_amount = list
    .find(&AssetInfo::native("uluna"))
    .unwrap()
    .amount;  // should have reduced to 2345

let len = list.len();  // should be zero, as uusd is purged from the list

pub fn transfer_msgs<A: Into<String> + Clone>( &self, to: A, ) -> Result<Vec<CosmosMsg>, AssetError>

Generate a transfer messages for every asset in the list

use cosmwasm_std::{Addr, Response};
use cw_asset::{AssetError, AssetList};

fn transfer_assets(list: &AssetList, recipient_addr: &Addr) -> Result<Response, AssetError> {
    let msgs = list.transfer_msgs(recipient_addr)?;

    Ok(Response::new().add_messages(msgs).add_attribute("assets_sent", list.to_string()))
}

Trait Implementations

impl<T: Clone + AddressLike> Clone for AssetListBase<T>

fn clone(&self) -> AssetListBase<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + AddressLike> Debug for AssetListBase<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: AddressLike> Default for AssetListBase<T>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for AssetListBase<T>

where T: Deserialize<'de> + AddressLike,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<AssetListBase<Addr>> for AssetListUnchecked

fn from(list: AssetList) -> Self

Converts to this type from the input type.

impl<T: AddressLike + JsonSchema> JsonSchema for AssetListBase<T>

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl<T: PartialEq + AddressLike> PartialEq for AssetListBase<T>

fn eq(&self, other: &AssetListBase<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Serialize for AssetListBase<T>

where T: Serialize + AddressLike,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: AddressLike> StructuralPartialEq for AssetListBase<T>