diff --git a/pop-api/src/lib.rs b/pop-api/src/lib.rs index 78a79f80f..cc785c141 100644 --- a/pop-api/src/lib.rs +++ b/pop-api/src/lib.rs @@ -1,3 +1,10 @@ +//! The `pop-api` crate provides an API for smart contracts to interact with the Pop Network runtime. +//! +//! This crate abstracts away complexities to deliver a streamlined developer experience while supporting +//! multiple API versions to ensure backward compatibility. It is designed with a focus on stability, +//! future-proofing, and storage efficiency, allowing developers to easily integrate powerful runtime +//! features into their contracts without unnecessary overhead. + #![cfg_attr(not(feature = "std"), no_std, no_main)] use constants::DECODING_FAILED; @@ -5,7 +12,9 @@ use ink::env::chain_extension::{ChainExtensionMethod, FromStatusCode}; #[cfg(feature = "assets")] pub use v0::assets; +/// Module providing primitives types. pub mod primitives; +/// The first version of the API. pub mod v0; /// A result type used by the API, with the `StatusCode` as the error type. @@ -27,13 +36,13 @@ mod constants { pub(crate) const FUNGIBLES: u8 = 150; } -/// Helper method to build `ChainExtensionMethod`. -/// -/// Parameters: -/// - 'version': The version of the chain extension. -/// - 'function': The ID of the function. -/// - 'module': The index of the runtime module. -/// - 'dispatchable': The index of the module dispatchable functions. +// Helper method to build a dispatch call or a call to read state. +// +// Parameters: +// - 'version': The version of the chain extension. +// - 'function': The ID of the function. +// - 'module': The index of the runtime module. +// - 'dispatchable': The index of the module dispatchable functions. fn build_extension_method( version: u8, function: u8, diff --git a/pop-api/src/v0/assets/fungibles.rs b/pop-api/src/v0/assets/fungibles.rs index 323db2b6e..c881f8234 100644 --- a/pop-api/src/v0/assets/fungibles.rs +++ b/pop-api/src/v0/assets/fungibles.rs @@ -1,3 +1,11 @@ +//! The `fungibles` module provides an API for interacting and managing fungible assets on Pop Network. +//! +//! The API includes the following interfaces: +//! 1. PSP-22 +//! 2. PSP-22 Metadata +//! 3. Asset Management +//! 4. PSP-22 Mintable & Burnable + use crate::{ constants::{ASSETS, BALANCES, FUNGIBLES}, primitives::{AccountId, AssetId, Balance}, @@ -8,28 +16,22 @@ use constants::*; use ink::{env::chain_extension::ChainExtensionMethod, prelude::vec::Vec}; pub use metadata::*; -/// Helper method to build a dispatch call `ChainExtensionMethod` for fungibles `v0`. -/// -/// Parameters: -/// - 'dispatchable': The index of the module dispatchable functions. +// Helper method to build a dispatch call. +// +// Parameters: +// - 'dispatchable': The index of the dispatchable function within the module. fn build_dispatch(dispatchable: u8) -> ChainExtensionMethod<(), (), (), false> { crate::v0::build_dispatch(FUNGIBLES, dispatchable) } -/// Helper method to build a dispatch call `ChainExtensionMethod` for fungibles `v0`. -/// -/// Parameters: -/// - 'state_query': The index of the runtime state query. +// Helper method to build a call to read state. +// +// Parameters: +// - 'state_query': The index of the runtime state query. fn build_read_state(state_query: u8) -> ChainExtensionMethod<(), (), (), false> { crate::v0::build_read_state(FUNGIBLES, state_query) } -/// Local Fungibles: -/// 1. PSP-22 Interface -/// 2. PSP-22 Metadata Interface -/// 3. Asset Management -/// 4. PSP-22 Mintable & Burnable Interface - mod constants { /// 1. PSP-22 Interface: pub(super) const TOTAL_SUPPLY: u8 = 0; @@ -147,9 +149,6 @@ pub mod events { /// /// # Parameters /// - `id` - The ID of the asset. -/// -/// # Returns -/// The total supply of the token, or an error if the operation fails. #[inline] pub fn total_supply(id: AssetId) -> Result { build_read_state(TOTAL_SUPPLY) @@ -165,9 +164,6 @@ pub fn total_supply(id: AssetId) -> Result { /// # Parameters /// - `id` - The ID of the asset. /// - `owner` - The account whose balance is being queried. -/// -/// # Returns -/// The balance of the specified account, or an error if the operation fails. #[inline] pub fn balance_of(id: AssetId, owner: AccountId) -> Result { build_read_state(BALANCE_OF) @@ -184,9 +180,6 @@ pub fn balance_of(id: AssetId, owner: AccountId) -> Result { /// - `id` - The ID of the asset. /// - `owner` - The account that owns the tokens. /// - `spender` - The account that is allowed to spend the tokens. -/// -/// # Returns -/// The remaining allowance, or an error if the operation fails. #[inline] pub fn allowance(id: AssetId, owner: AccountId, spender: AccountId) -> Result { build_read_state(ALLOWANCE) @@ -203,9 +196,6 @@ pub fn allowance(id: AssetId, owner: AccountId, spender: AccountId) -> Result Result<()> { build_dispatch(TRANSFER) @@ -223,9 +213,6 @@ pub fn transfer(id: AssetId, to: AccountId, value: Balance) -> Result<()> { /// - `from` - The account from which the tokens are transferred. /// - `to` - The recipient account. /// - `value` - The number of tokens to transfer. -/// -/// # Returns -/// Returns `Ok(())` if successful, or an error if the transfer fails. #[inline] pub fn transfer_from(id: AssetId, from: AccountId, to: AccountId, value: Balance) -> Result<()> { build_dispatch(TRANSFER_FROM) @@ -241,9 +228,6 @@ pub fn transfer_from(id: AssetId, from: AccountId, to: AccountId, value: Balance /// - `id` - The ID of the asset. /// - `spender` - The account that is allowed to spend the tokens. /// - `value` - The number of tokens to approve. -/// -/// # Returns -/// Returns `Ok(())` if successful, or an error if the approval fails. #[inline] pub fn approve(id: AssetId, spender: AccountId, value: Balance) -> Result<()> { build_dispatch(APPROVE) @@ -259,9 +243,6 @@ pub fn approve(id: AssetId, spender: AccountId, value: Balance) -> Result<()> { /// - `id` - The ID of the asset. /// - `spender` - The account that is allowed to spend the tokens. /// - `value` - The number of tokens to increase the allowance by. -/// -/// # Returns -/// Returns `Ok(())` if successful, or an error if the operation fails. #[inline] pub fn increase_allowance(id: AssetId, spender: AccountId, value: Balance) -> Result<()> { build_dispatch(INCREASE_ALLOWANCE) @@ -277,9 +258,6 @@ pub fn increase_allowance(id: AssetId, spender: AccountId, value: Balance) -> Re /// - `id` - The ID of the asset. /// - `spender` - The account that is allowed to spend the tokens. /// - `value` - The number of tokens to decrease the allowance by. -/// -/// # Returns -/// Returns `Ok(())` if successful, or an error if the operation fails. #[inline] pub fn decrease_allowance(id: AssetId, spender: AccountId, value: Balance) -> Result<()> { build_dispatch(DECREASE_ALLOWANCE) @@ -295,9 +273,7 @@ pub fn decrease_allowance(id: AssetId, spender: AccountId, value: Balance) -> Re /// - `id` - The ID of the asset. /// - `account` - The account to be credited with the created tokens. /// - `value` - The number of tokens to mint. -/// -/// # Returns -/// Returns `Ok(())` if successful, or an error if the operation fails. +#[inline] pub fn mint(id: AssetId, account: AccountId, value: Balance) -> Result<()> { build_dispatch(MINT) .input::<(AssetId, AccountId, Balance)>() @@ -312,9 +288,7 @@ pub fn mint(id: AssetId, account: AccountId, value: Balance) -> Result<()> { /// - `id` - The ID of the asset. /// - `account` - The account from which the tokens will be destroyed. /// - `value` - The number of tokens to destroy. -/// -/// # Returns -/// Returns `Ok(())` if successful, or an error if the operation fails. +#[inline] pub fn burn(id: AssetId, account: AccountId, value: Balance) -> Result<()> { build_dispatch(BURN) .input::<(AssetId, AccountId, Balance)>() @@ -323,6 +297,7 @@ pub fn burn(id: AssetId, account: AccountId, value: Balance) -> Result<()> { .call(&(id, account, value)) } +/// The PSP-22 Metadata interface for querying metadata. pub mod metadata { use super::*; @@ -330,9 +305,6 @@ pub mod metadata { /// /// # Parameters /// - `id` - The ID of the asset. - /// - /// # Returns - /// The name of the token as a byte vector, or an error if the operation fails. #[inline] pub fn token_name(id: AssetId) -> Result> { build_read_state(TOKEN_NAME) @@ -346,9 +318,6 @@ pub mod metadata { /// /// # Parameters /// - `id` - The ID of the asset. - /// - /// # Returns - /// The symbol of the token as a byte vector, or an error if the operation fails. #[inline] pub fn token_symbol(id: AssetId) -> Result> { build_read_state(TOKEN_SYMBOL) @@ -362,9 +331,6 @@ pub mod metadata { /// /// # Parameters /// - `id` - The ID of the asset. - /// - /// # Returns - /// The number of decimals of the token, or an error if the operation fails. #[inline] pub fn token_decimals(id: AssetId) -> Result { build_read_state(TOKEN_DECIMALS) @@ -375,7 +341,8 @@ pub mod metadata { } } -pub mod asset_management { +/// The interface for creating, managing and destroying fungible assets. +pub mod management { use super::*; /// Create a new token with a given asset ID. @@ -384,9 +351,7 @@ pub mod asset_management { /// - `id` - The ID of the asset. /// - `admin` - The account that will administer the asset. /// - `min_balance` - The minimum balance required for accounts holding this asset. - /// - /// # Returns - /// Returns `Ok(())` if successful, or an error if the creation fails. + #[inline] pub fn create(id: AssetId, admin: AccountId, min_balance: Balance) -> Result<()> { build_dispatch(CREATE) .input::<(AssetId, AccountId, Balance)>() @@ -399,9 +364,7 @@ pub mod asset_management { /// /// # Parameters /// - `id` - The ID of the asset. - /// - /// # Returns - /// Returns `Ok(())` if successful, or an error if the operation fails. + #[inline] pub fn start_destroy(id: AssetId) -> Result<()> { build_dispatch(START_DESTROY) .input::() @@ -417,9 +380,7 @@ pub mod asset_management { /// - `name`: The user friendly name of this asset. Limited in length by `StringLimit`. /// - `symbol`: The exchange symbol for this asset. Limited in length by `StringLimit`. /// - `decimals`: The number of decimals this asset uses to represent one unit. - /// - /// # Returns - /// Returns `Ok(())` if successful, or an error if the operation fails. + #[inline] pub fn set_metadata(id: AssetId, name: Vec, symbol: Vec, decimals: u8) -> Result<()> { build_dispatch(SET_METADATA) .input::<(AssetId, Vec, Vec, u8)>() @@ -432,9 +393,7 @@ pub mod asset_management { /// /// # Parameters /// - `id` - The ID of the asset. - /// - /// # Returns - /// Returns `Ok(())` if successful, or an error if the operation fails. + #[inline] pub fn clear_metadata(id: AssetId) -> Result<()> { build_dispatch(CLEAR_METADATA) .input::() diff --git a/pop-api/src/v0/assets/mod.rs b/pop-api/src/v0/assets/mod.rs index 197db7107..2d5ae236d 100644 --- a/pop-api/src/v0/assets/mod.rs +++ b/pop-api/src/v0/assets/mod.rs @@ -1,2 +1,3 @@ +/// APIs for fungible assets. #[cfg(feature = "fungibles")] pub mod fungibles; diff --git a/pop-api/src/v0/mod.rs b/pop-api/src/v0/mod.rs index 0fd06c89e..a4824327d 100644 --- a/pop-api/src/v0/mod.rs +++ b/pop-api/src/v0/mod.rs @@ -6,6 +6,7 @@ use crate::{ }; use ink::env::chain_extension::ChainExtensionMethod; +/// APIs for asset-related use cases. #[cfg(feature = "assets")] pub mod assets; @@ -17,20 +18,20 @@ impl From for Error { } } -/// Helper method to build a dispatch call `ChainExtensionMethod` -/// -/// Parameters: -/// - 'module': The index of the runtime module -/// - 'dispatchable': The index of the module dispatchable functions +// Helper method to build a dispatch call. +// +// Parameters: +// - 'module': The index of the runtime module. +// - 'dispatchable': The index of the module dispatchable functions. fn build_dispatch(module: u8, dispatchable: u8) -> ChainExtensionMethod<(), (), (), false> { build_extension_method(V0, DISPATCH, module, dispatchable) } -/// Helper method to build a dispatch call `ChainExtensionMethod` -/// -/// Parameters: -/// - 'module': The index of the runtime module -/// - 'state_query': The index of the runtime state query +// Helper method to build a call to read state. +// +// Parameters: +// - 'module': The index of the runtime module. +// - 'state_query': The index of the runtime state query. fn build_read_state(module: u8, state_query: u8) -> ChainExtensionMethod<(), (), (), false> { build_extension_method(V0, READ_STATE, module, state_query) }