Skip to content

Commit

Permalink
docs: pop api (#190)
Browse files Browse the repository at this point in the history 
Co-authored-by: Frank Bell <[email protected]>
  • Loading branch information
@Daanvdplas @evilrobot-01
Daanvdplas and evilrobot-01 authored Aug 16, 2024
1 parent 8b4f595 commit f13b39c
Show file tree
Hide file tree
Showing 4 changed files with 53 additions and 83 deletions.
23 changes: 16 additions & 7 deletions pop-api/src/lib.rs
View file
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
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
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
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)
}

0 comments on commit f13b39c

Please sign in to comment.