cw_asset/lib.rs
1#![forbid(unsafe_code)]
2//! A unified representation of various types of Cosmos fungible assets, and helper functions for
3//! interacting with them
4//!
5//! ## Basic usage
6//!
7//! The following code generates messages the sends some SDK coins and CW20 tokens to a recipient:
8//!
9//! ```rust
10//! use cosmwasm_std::{Api, Response};
11//! use cw_asset::{Asset, AssetError};
12//!
13//! fn transfer_two_assets(api: &dyn Api) -> Result<Response, AssetError> {
14//! let asset1 = Asset::native("uusd", 12345u128);
15//! let msg1 = asset1.transfer_msg("recipient_addr")?;
16//!
17//! let asset2 = Asset::cw20(api.addr_validate("token_addr")?, 67890u128);
18//! let msg2 = asset1.transfer_msg("recipient_addr")?;
19//!
20//! Ok(Response::new()
21//! .add_message(msg1)
22//! .add_message(msg2)
23//! .add_attribute("asset_sent", asset1.to_string())
24//! .add_attribute("asset_sent", asset2.to_string()))
25//! }
26//! ```
27//!
28//! ## Asset list
29//!
30//! An [`AssetList`] struct is also provided for dealing with multiple assets at the same time:
31//!
32//! ```rust
33//! use cosmwasm_std::{Api, Response};
34//! use cw_asset::{Asset, AssetError, AssetList};
35//!
36//! fn transfer_multiple_assets(api: &dyn Api) -> Result<Response, AssetError> {
37//! let assets = AssetList::from(vec![
38//! Asset::native("uusd", 12345u128),
39//! Asset::cw20(api.addr_validate("token_addr")?, 67890u128),
40//! ]);
41//!
42//! let msgs = assets.transfer_msgs(api.addr_validate("recipient_addr")?)?;
43//!
44//! Ok(Response::new().add_messages(msgs).add_attribute("assets_sent", assets.to_string()))
45//! }
46//! ```
47//!
48//! ## Use in messages
49//!
50//! [`Asset`] and [`AssetList`] each comes with an _unchecked_ counterpart which contains unverified
51//! addresses and/or denoms, and implements traits that allow them to be serialized into JSON, so
52//! that they can be directly used in Cosmos messages:
53//!
54//! ```rust
55//! use cosmwasm_schema::cw_serde;
56//! use cw_asset::AssetUnchecked;
57//!
58//! #[cw_serde]
59//! pub enum ExecuteMsg {
60//! Deposit {
61//! asset: AssetUnchecked,
62//! },
63//! }
64//! ```
65//!
66//! Although [`Asset`] and [`AssetList`] _also_ implement the related traits, hence can also be used
67//! in messages, it is not recommended to do so; it is a good security practice to never trust
68//! addresses passed in by messages to be valid. Instead, also validate them yourselves:
69//!
70//! ```rust
71//! use cosmwasm_std::{Api, StdResult};
72//! use cw_asset::{Asset, AssetError, AssetUnchecked};
73//!
74//! const ACCEPTED_DENOMS: &[&str] = &["uatom", "uosmo", "uluna"];
75//!
76//! fn validate_deposit(api: &dyn Api, asset_unchecked: AssetUnchecked) -> Result<(), AssetError> {
77//! let asset: Asset = asset_unchecked.check(api, Some(ACCEPTED_DENOMS))?;
78//! Ok(())
79//! }
80//! ```
81
82mod asset;
83mod asset_info;
84mod asset_list;
85mod error;
86
87pub use asset::{Asset, AssetBase, AssetUnchecked};
88pub use asset_info::{AssetInfo, AssetInfoBase, AssetInfoUnchecked};
89pub use asset_list::{AssetList, AssetListBase, AssetListUnchecked};
90pub use error::AssetError;
91
92#[cfg(test)]
93mod testing;