Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: pop api #190

Merged
merged 6 commits into from
Aug 16, 2024
Merged

docs: pop api #190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d271257
docs: pop api
Daanvdplas Aug 14, 2024
65e2139
style: general
Daanvdplas Aug 15, 2024
7731a26
style: remove return docs
Daanvdplas Aug 15, 2024
d3ca674
fix: consistent inline
Daanvdplas Aug 15, 2024
66e6889
refactor: conforming to psp22 metadata standard
Daanvdplas Aug 15, 2024
dfb7e3e
Update pop-api/src/v0/assets/fungibles.rs
Daanvdplas Aug 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions pop-api/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,20 @@
//! 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;
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.
Expand All @@ -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,
Expand Down
91 changes: 25 additions & 66 deletions pop-api/src/v0/assets/fungibles.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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},
Expand All @@ -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;
Expand Down Expand Up @@ -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<Balance> {
build_read_state(TOTAL_SUPPLY)
Expand All @@ -165,9 +164,6 @@ pub fn total_supply(id: AssetId) -> Result<Balance> {
/// # 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<Balance> {
build_read_state(BALANCE_OF)
Expand All @@ -184,9 +180,6 @@ pub fn balance_of(id: AssetId, owner: AccountId) -> Result<Balance> {
/// - `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<Balance> {
build_read_state(ALLOWANCE)
Expand All @@ -203,9 +196,6 @@ pub fn allowance(id: AssetId, owner: AccountId, spender: AccountId) -> Result<Ba
/// - `id` - The ID of the asset.
/// - `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(id: AssetId, to: AccountId, value: Balance) -> Result<()> {
build_dispatch(TRANSFER)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)>()
Expand All @@ -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)>()
Expand All @@ -323,16 +297,14 @@ 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::*;

/// Returns the token name for a given asset ID.
///
/// # 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<Vec<u8>> {
build_read_state(TOKEN_NAME)
Expand All @@ -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<Vec<u8>> {
build_read_state(TOKEN_SYMBOL)
Expand All @@ -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<u8> {
build_read_state(TOKEN_DECIMALS)
Expand All @@ -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.
Expand All @@ -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)>()
Expand All @@ -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::<AssetId>()
Expand All @@ -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<u8>, symbol: Vec<u8>, decimals: u8) -> Result<()> {
build_dispatch(SET_METADATA)
.input::<(AssetId, Vec<u8>, Vec<u8>, u8)>()
Expand All @@ -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::<AssetId>()
Expand Down
1 change: 1 addition & 0 deletions pop-api/src/v0/assets/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
/// APIs for fungible assets.
#[cfg(feature = "fungibles")]
pub mod fungibles;
21 changes: 11 additions & 10 deletions pop-api/src/v0/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ use crate::{
};
use ink::env::chain_extension::ChainExtensionMethod;

/// APIs for asset-related use cases.
#[cfg(feature = "assets")]
pub mod assets;

Expand All @@ -17,20 +18,20 @@ impl From<StatusCode> 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)
}
Loading