Skip to content

Commit

Permalink
format comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@larry0x
larry0x committed Feb 2, 2023
1 parent d499288 commit 6550644
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 76 deletions.
69 changes: 38 additions & 31 deletions src/asset.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ use crate::{AssetInfo, AssetInfoBase, AssetInfoUnchecked, AssetError};

/// Represents a fungible asset with a known amount
///
/// Each asset instance contains two values: [`info`], which specifies the asset's type (CW20 or
/// native), and its [`amount`], which specifies the asset's amount
/// Each asset instance contains two values: `info`, which specifies the asset's
/// type (CW20 or native), and its `amount`, which specifies the asset's amount.
#[cw_serde]
pub struct AssetBase<T: AddressLike> {
/// Specifies the asset's type (CW20 or native)
Expand All @@ -24,8 +24,9 @@ pub struct AssetBase<T: AddressLike> {
impl<T: AddressLike> AssetBase<T> {
/// Create a new **asset** instance based on given asset info and amount
///
/// To create an unchecked instance, the [`info`] parameter may be either checked or unchecked;
/// to create a checked instance, the [`info`] paramter must also be checked.
/// To create an unchecked instance, the `info` parameter may be either
/// checked or unchecked; to create a checked instance, the `info` paramter
/// must also be checked.
///
/// ```rust
/// use cosmwasm_std::Addr;
Expand Down Expand Up @@ -58,11 +59,8 @@ impl<T: AddressLike> AssetBase<T> {
}
}

/// Create a new **asset** instance representing a CW20 token of given contract address and amount
///
/// To create an unchecked instance, provide the contract address in any of the following types:
/// [`cosmwasm_std::Addr`], [`String`], or [`&str`]; to create a checked instance, the address
/// must of type [`cosmwasm_std::Addr`].
/// Create a new **asset** instance representing a CW20 token of given
/// contract address and amount.
///
/// ```rust
/// use cosmwasm_std::Addr;
Expand All @@ -78,10 +76,12 @@ impl<T: AddressLike> AssetBase<T> {
}
}

// Represents an **asset** instance that may contain unverified data; to be used in messages
// Represents an **asset** instance that may contain unverified data; to be used
// in messages.
pub type AssetUnchecked = AssetBase<String>;

// Represents an **asset** instance containing only verified data; to be saved in contract storage
// Represents an **asset** instance containing only verified data; to be saved
// in contract storage.
pub type Asset = AssetBase<Addr>;

impl FromStr for AssetUnchecked {
Expand Down Expand Up @@ -130,16 +130,18 @@ impl From<Asset> for AssetUnchecked {
}

impl AssetUnchecked {
/// Parse a string of the format `{amount}{denom}` into an `AssetUnchecked` object. This is the
/// format that Cosmos SDK uses to stringify native coins. For example:
/// Parse a string of the format `{amount}{denom}` into an `AssetUnchecked`
/// object. This is the format that Cosmos SDK uses to stringify native
/// coins. For example:
///
/// - `12345uatom`
/// - `69420ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2`
/// - `88888factory/osmo1z926ax906k0ycsuckele6x5hh66e2m4m6ry7dn`
///
/// Since native coin denoms can only start with a non-numerial character, while its amount can
/// only contain numerical characters, we simply consider the first non-numerical character and
/// all that comes after as the denom, while all that comes before it as the amount. This is the
/// Since native coin denoms can only start with a non-numerial character,
/// while its amount can only contain numerical characters, we simply
/// consider the first non-numerical character and all that comes after as
/// the denom, while all that comes before it as the amount. This is the
/// approach used in the [Steak Hub contract](https://github.com/st4k3h0us3/steak-contracts/blob/v1.0.0/contracts/hub/src/helpers.rs#L48-L68).
pub fn from_sdk_string(s: &str) -> Result<Self, AssetError> {
for (i, c) in s.chars().enumerate() {
Expand All @@ -155,11 +157,12 @@ impl AssetUnchecked {
})
}

/// Validate data contained in an _unchecked_ **asset** instnace, return a new _checked_
/// **asset** 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
/// Validate data contained in an _unchecked_ **asset** instnace, return a
/// new _checked_ **asset** 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.
///
/// ```rust
/// use cosmwasm_std::{Addr, Api};
Expand Down Expand Up @@ -240,10 +243,12 @@ impl std::cmp::PartialEq<Coin> for Asset {
}

impl Asset {
/// Generate a message that sends a CW20 token to the specified recipient with a binary payload
/// Generate a message that sends a CW20 token to the specified recipient
/// with a binary payload.
///
/// NOTE: Only works for CW20 tokens. Returns error if invoked on an [`Asset`] instance
/// representing a native coin, as native coins do not have an equivalent method mplemented.
/// NOTE: Only works for CW20 tokens. Returns error if invoked on an `Asset`
/// instance representing a native coin, as native coins do not have an
/// equivalent method mplemented.
///
/// ```rust
/// use serde::Serialize;
Expand Down Expand Up @@ -283,7 +288,8 @@ impl Asset {
}
}

/// Generate a message that transfers the asset from the sender to to a specified account
/// Generate a message that transfers the asset from the sender to to a
/// specified account.
///
/// ```rust
/// use cosmwasm_std::{Addr, Response, StdResult};
Expand Down Expand Up @@ -315,11 +321,12 @@ impl Asset {
}
}

/// Generate a message that draws the asset from the account specified by [`from`] to the one
/// specified by [`to`]
/// Generate a message that draws the asset from the account specified by
/// `from` to the one specified by `to`.
///
/// NOTE: Only works for CW20 tokens. Returns error if invoked on an [`Asset`] instance
/// representing a native coin, as native coins do not have an equivalent method mplemented.
/// NOTE: Only works for CW20 tokens. Returns error if invoked on an `Asset`
/// instance representing a native coin, as native coins do not have an
/// equivalent method implemented.
///
/// ```rust
/// use cosmwasm_std::{Addr, Response, StdResult};
Expand Down Expand Up @@ -353,9 +360,9 @@ impl Asset {
}
}

//--------------------------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// Tests
//--------------------------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#[cfg(test)]
mod tests {
Expand Down
40 changes: 21 additions & 19 deletions src/asset_info.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,14 @@ use cw_storage_plus::{Key, KeyDeserialize, Prefixer, PrimaryKey};

use crate::AssetError;

/// Represents the type of an fungible asset
/// Represents the type of an fungible asset.
///
/// Each **asset info** instance can be one of three variants:
///
/// - Native SDK coins. To create an **asset info** instance of this type, provide the denomination.
/// - CW20 tokens. To create an **asset info** instance of this type, provide the contract address.
/// - CW1155 tokens. To create an **asset info** instance of this type, provide the contract address and token ID.
/// - Native SDK coins. To create an **asset info** instance of this type,
/// provide the denomination.
/// - CW20 tokens. To create an **asset info** instance of this type, provide
/// the contract address.
#[cw_serde]
#[non_exhaustive]
pub enum AssetInfoBase<T: AddressLike> {
Expand All @@ -26,7 +27,8 @@ pub enum AssetInfoBase<T: AddressLike> {
}

impl<T: AddressLike> AssetInfoBase<T> {
/// Create an **asset info** instance of the _native_ variant by providing the coin's denomination
/// Create an **asset info** instance of the _native_ variant by providing
/// the coin's denomination.
///
/// ```rust
/// use cw_asset::AssetInfo;
Expand All @@ -39,10 +41,6 @@ impl<T: AddressLike> AssetInfoBase<T> {

/// Create an **asset info** instance of the _CW20_ variant
///
/// To create an unchecked instance, provide the contract address in any of the following types:
/// [`cosmwasm_std::Addr`], [`String`], or [`&str`]; to create a checked instance, the address
/// must of type [`cosmwasm_std::Addr`].
///
/// ```rust
/// use cosmwasm_std::Addr;
/// use cw_asset::AssetInfo;
Expand All @@ -54,10 +52,12 @@ impl<T: AddressLike> AssetInfoBase<T> {
}
}

/// Represents an **asset info** instance that may contain unverified data; to be used in messages
/// Represents an **asset info** instance that may contain unverified data; to
/// be used in messages.
pub type AssetInfoUnchecked = AssetInfoBase<String>;

/// Represents an **asset info** instance containing only verified data; to be saved in contract storage
/// Represents an **asset info** instance containing only verified data; to be
/// saved in contract storage.
pub type AssetInfo = AssetInfoBase<Addr>;

impl FromStr for AssetInfoUnchecked {
Expand Down Expand Up @@ -111,11 +111,12 @@ impl From<&AssetInfo> for AssetInfoUnchecked {
}

impl AssetInfoUnchecked {
/// Validate data contained in an _unchecked_ **asset info** instance; return a new _checked_
/// **asset info** 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
/// Validate data contained in an _unchecked_ **asset info** instance;
/// return a new _checked_ **asset info** 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.
///
///
/// ```rust
Expand Down Expand Up @@ -259,7 +260,8 @@ impl KeyDeserialize for AssetInfo {
#[inline(always)]
fn from_vec(mut value: Vec<u8>) -> StdResult<Self::Output> {
// ignore length prefix
// we're allowed to do this because we set the key's namespace ourselves in PrimaryKey (first key)
// we're allowed to do this because we set the key's namespace ourselves
// in PrimaryKey (first key)
value.drain(0..2);

// parse the bytes into an utf8 string
Expand All @@ -277,9 +279,9 @@ impl<'a> Prefixer<'a> for AssetInfo {
}
}

//--------------------------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// Tests
//--------------------------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#[cfg(test)]
mod test {
Expand Down
59 changes: 33 additions & 26 deletions src/asset_list.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,12 @@ impl<T: AddressLike> Default for AssetListBase<T> {
}
}

/// Represents an **asset list** instance that may contain unverified data; to be used in messages
/// Represents an **asset list** instance that may contain unverified data; to
/// be used in messages.
pub type AssetListUnchecked = AssetListBase<String>;

/// Represents an **asset list** instance containing only verified data; to be used in contract storage
/// Represents an **asset list** instance containing only verified data; to be
/// used in contract storage.
pub type AssetList = AssetListBase<Addr>;

impl FromStr for AssetListUnchecked {
Expand All @@ -46,10 +48,11 @@ impl From<AssetList> for AssetListUnchecked {
}

impl AssetListUnchecked {
/// 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
/// 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
///
/// ```rust
Expand Down Expand Up @@ -192,8 +195,8 @@ impl AssetList {
/// let len = list.len(); // should be two
/// ```
///
// NOTE: I do have `is_empty` implemented, but clippy still throws a warning saying I don't have
// it. Must be a clippy bug...
// NOTE: I do have `is_empty` implemented, but clippy still throws a warnin
// saying I don't have it. Must be a clippy bug...
#[allow(clippy::len_without_is_empty)]
pub fn len(&self) -> usize {
self.0.len()
Expand All @@ -216,11 +219,11 @@ impl AssetList {

/// 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.
/// 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:
/// A case where is method is useful is to find how much asset the user sent
/// along with a message:
///
/// ```rust
/// use cosmwasm_std::MessageInfo;
Expand All @@ -240,14 +243,16 @@ impl AssetList {

/// 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:
/// An example case where this is useful is to scale the amount of each
/// asset in the list by a certain factor:
///
/// ```rust
/// use cw_asset::{Asset, AssetInfo, AssetList};
///
/// let mut list =
/// AssetList::from(vec![Asset::native("uluna", 12345u128), Asset::native("uusd", 67890u128)]);
/// 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));
/// ```
Expand Down Expand Up @@ -277,11 +282,11 @@ impl AssetList {

/// 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.
/// 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.
/// NOTE: `purge` is automatically performed following the addition, so
/// adding an asset with zero amount has no effect.
///
/// ```rust
/// use cw_asset::{Asset, AssetInfo, AssetList};
Expand Down Expand Up @@ -346,11 +351,13 @@ impl AssetList {

/// 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.
/// 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.
/// 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};
Expand Down Expand Up @@ -434,9 +441,9 @@ impl AssetList {
}
}

//--------------------------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// Tests
//--------------------------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#[cfg(test)]
mod test_helpers {
Expand Down

0 comments on commit 6550644

Please sign in to comment.