update docs

Author: xlc

guest-examples/sum-balance-percent/src/main.rs

@@ -1,16 +1,37 @@
+//! A guest program that sums the balances of a set of accounts for a given asset and returns the percentage of the total supply.
 #![no_std]
 #![no_main]
 
+/// The primary module for the sum-balance-percent guest program.
+///
+/// This module defines the necessary types, extension functions, and the main entrypoint
+/// for calculating the percentage of total supply represented by the sum of balances
+/// for a given set of accounts.
 #[pvq_program::program]
 mod sum_balance_percent {
+    /// A type alias for the asset identifier.
     type AssetId = u32;
+    /// A type alias for the account identifier.
     type AccountId = [u8; 32];
+    /// A type alias for the balance of an account.
     type Balance = u64;
+
+    /// Retrieves the balance of a specific account for a given asset.
+    ///
+    /// This is an extension function that calls into the runtime.
     #[program::extension_fn(extension_id = 1248491991627109725u64, fn_index = 6)]
     fn balance(asset: AssetId, who: AccountId) -> Balance {}
+
+    /// Retrieves the total supply of a given asset.
+    ///
+    /// This is an extension function that calls into the runtime.
     #[program::extension_fn(extension_id = 1248491991627109725u64, fn_index = 5)]
     fn total_supply(asset: AssetId) -> Balance {}
 
+    /// The entrypoint of the program.
+    ///
+    /// It takes an asset ID and a vector of account IDs, calculates the sum of their balances,
+    /// and returns the percentage of this sum with respect to the total supply of the asset.
     #[program::entrypoint]
     fn sum_balance(asset: AssetId, accounts: alloc::vec::Vec<AccountId>) -> Balance {
         let mut sum_balance = 0;

guest-examples/sum-balance/src/main.rs

@@ -1,28 +1,59 @@
+//! A guest program that sums the balance of a given asset for a list of accounts.
 #![no_std]
 #![no_main]
 
+/// A guest program that sums the balance of a given asset for a list of accounts.
 #[pvq_program::program]
 mod sum_balance {
 
     cfg_if::cfg_if! {
         if #[cfg(feature = "option_version_1")] {
+            /// Represents a unique identifier for an account.
             type AccountId = [u8; 64];
+            /// Represents a unique identifier for an asset.
             type AssetId = u64;
+            /// Represents the balance of an asset.
             type Balance = u128;
         } else if #[cfg(feature = "option_version_2")] {
+            /// Represents a unique identifier for an account.
             type AccountId = [u8; 32];
+            /// Represents a unique identifier for an asset.
             type AssetId = u32;
+            /// Represents the balance of an asset.
             type Balance = u64;
         } else {
+            /// Represents a unique identifier for an account.
             type AccountId = [u8; 32];
+            /// Represents a unique identifier for an asset.
             type AssetId = u32;
+            /// Represents the balance of an asset.
             type Balance = u64;
         }
     }
 
+    /// Get the balance of a given asset for a specific account.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: The identifier of the asset.
+    /// * `who`: The account identifier.
+    ///
+    /// # Returns
+    ///
+    /// The balance of the asset for the specified account.
     #[program::extension_fn(extension_id = 1248491991627109725u64, fn_index = 6)]
     fn balance(asset: AssetId, who: AccountId) -> Balance {}
 
+    /// Sums the balance of a given asset for a list of accounts.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: The identifier of the asset.
+    /// * `accounts`: A list of account identifiers.
+    ///
+    /// # Returns
+    ///
+    /// The total balance of the asset for all the specified accounts.
     #[program::entrypoint]
     fn sum_balance(asset: AssetId, accounts: alloc::vec::Vec<AccountId>) -> Balance {
         let mut sum = 0;

guest-examples/swap-info/src/main.rs

@@ -1,21 +1,42 @@
+//! A guest program that provides information about asset swaps.
 #![no_std]
 #![no_main]
 
+/// A guest program that provides information about asset swaps.
 #[pvq_program::program]
 mod swap_info {
 
+    /// Represents a unique identifier for an asset.
     type AssetId = alloc::vec::Vec<u8>;
+    /// Represents the balance of an asset.
     type Balance = u128;
+    /// Represents information about an asset.
     #[derive(
         Debug, Clone, PartialEq, Eq, parity_scale_codec::Encode, parity_scale_codec::Decode, scale_info::TypeInfo,
     )]
     pub struct AssetInfo {
+        /// The unique identifier of the asset.
         pub asset_id: AssetId,
+        /// The name of the asset.
         pub name: alloc::vec::Vec<u8>,
+        /// The symbol of the asset.
         pub symbol: alloc::vec::Vec<u8>,
+        /// The number of decimals the asset has.
         pub decimals: u8,
     }
 
+    /// Get the quote price of `asset1` in terms of `asset2` for a given amount of `asset2`.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset1`: The identifier of the asset to be quoted.
+    /// * `asset2`: The identifier of the asset to quote against.
+    /// * `amount`: The amount of `asset2`.
+    /// * `include_fee`: Whether to include the fee in the quote.
+    ///
+    /// # Returns
+    ///
+    /// The quote price of `asset1` in terms of `asset2`, or `None` if the quote is not available.
     #[program::extension_fn(extension_id = 15900548380266538526u64, fn_index = 0)]
     fn quote_price_tokens_for_exact_tokens(
         asset1: AssetId,
@@ -25,6 +46,18 @@ mod swap_info {
     ) -> Option<Balance> {
     }
 
+    /// Get the quote price of `asset2` in terms of `asset1` for a given amount of `asset1`.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset1`: The identifier of the asset to quote against.
+    /// * `asset2`: The identifier of the asset to be quoted.
+    /// * `amount`: The amount of `asset1`.
+    /// * `include_fee`: Whether to include the fee in the quote.
+    ///
+    /// # Returns
+    ///
+    /// The quote price of `asset2` in terms of `asset1`, or `None` if the quote is not available.
     #[program::extension_fn(extension_id = 15900548380266538526u64, fn_index = 1)]
     fn quote_price_exact_tokens_for_tokens(
         asset1: AssetId,
@@ -34,18 +67,58 @@ mod swap_info {
     ) -> Option<Balance> {
     }
 
+    /// Get the liquidity pool of two assets.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset1`: The identifier of the first asset.
+    /// * `asset2`: The identifier of the second asset.
+    ///
+    /// # Returns
+    ///
+    /// A tuple containing the balance of each asset in the liquidity pool, or `None` if the pool does not exist.
     #[program::extension_fn(extension_id = 15900548380266538526u64, fn_index = 2)]
     fn get_liquidity_pool(asset1: AssetId, asset2: AssetId) -> Option<(Balance, Balance)> {}
 
+    /// List all available liquidity pools.
+    ///
+    /// # Returns
+    ///
+    /// A list of tuples, where each tuple represents a liquidity pool and contains the identifiers of the two assets in the pool.
     #[program::extension_fn(extension_id = 15900548380266538526u64, fn_index = 3)]
     fn list_pools() -> alloc::vec::Vec<(AssetId, AssetId)> {}
 
+    /// Get information about a specific asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: The identifier of the asset.
+    ///
+    /// # Returns
+    ///
+    /// Information about the asset, or `None` if the asset does not exist.
     #[program::extension_fn(extension_id = 15900548380266538526u64, fn_index = 4)]
     fn asset_info(asset: AssetId) -> Option<AssetInfo> {}
 
+    /// Get information about all assets.
+    ///
+    /// # Returns
+    ///
+    /// A map of asset identifiers to asset information.
     #[program::extension_fn(extension_id = 15900548380266538526u64, fn_index = 5)]
     fn assets_info() -> alloc::collections::BTreeMap<AssetId, AssetInfo> {}
 
+    /// Get the quote price of `asset2` in terms of `asset1` for a given amount of `asset1`.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset1`: The identifier of the asset to quote against.
+    /// * `asset2`: The identifier of the asset to be quoted.
+    /// * `amount`: The amount of `asset1`.
+    ///
+    /// # Returns
+    ///
+    /// The quote price of `asset2` in terms of `asset1`, or `None` if the quote is not available.
     #[program::entrypoint]
     fn entrypoint_quote_price_exact_tokens_for_tokens(
         asset1: AssetId,
@@ -55,6 +128,17 @@ mod swap_info {
         quote_price_exact_tokens_for_tokens(asset1, asset2, amount, true)
     }
 
+    /// Get the quote price of `asset1` in terms of `asset2` for a given amount of `asset2`.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset1`: The identifier of the asset to be quoted.
+    /// * `asset2`: The identifier of the asset to quote against.
+    /// * `amount`: The amount of `asset2`.
+    ///
+    /// # Returns
+    ///
+    /// The quote price of `asset1` in terms of `asset2`, or `None` if the quote is not available.
     #[program::entrypoint]
     fn entrypoint_quote_price_tokens_for_exact_tokens(
         asset1: AssetId,
@@ -64,11 +148,26 @@ mod swap_info {
         quote_price_tokens_for_exact_tokens(asset1, asset2, amount, true)
     }
 
+    /// Get the liquidity pool of two assets.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset1`: The identifier of the first asset.
+    /// * `asset2`: The identifier of the second asset.
+    ///
+    /// # Returns
+    ///
+    /// A tuple containing the balance of each asset in the liquidity pool, or `None` if the pool does not exist.
     #[program::entrypoint]
     fn entrypoint_get_liquidity_pool(asset1: AssetId, asset2: AssetId) -> Option<(Balance, Balance)> {
         get_liquidity_pool(asset1, asset2)
     }
 
+    /// List all available liquidity pools with their asset information.
+    ///
+    /// # Returns
+    ///
+    /// A list of tuples, where each tuple represents a liquidity pool and contains the information of the two assets in the pool.
     #[program::entrypoint]
     fn entrypoint_list_pools() -> alloc::vec::Vec<(AssetInfo, AssetInfo)> {
         let pools = list_pools();

guest-examples/total-supply/src/main.rs

@@ -1,11 +1,31 @@
+//! A guest program that queries the total supply of a given asset.
 #![no_std]
 #![no_main]
 
+/// A guest program that queries the total supply of a given asset.
 #[pvq_program::program]
 mod query_total_supply {
+    /// Get the total supply of a given asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: The identifier of the asset.
+    ///
+    /// # Returns
+    ///
+    /// The total supply of the asset.
     #[program::extension_fn(extension_id = 4071833530116166512u64, fn_index = 0)]
     fn total_supply(asset: u32) -> u64 {}
 
+    /// Get the total supply of a given asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: The identifier of the asset.
+    ///
+    /// # Returns
+    ///
+    /// The total supply of the asset.
     #[program::entrypoint]
     fn get_total_supply(asset: u32) -> u64 {
         total_supply(asset)

pvq-executor/src/context.rs

@@ -1,8 +1,13 @@
 use polkavm::Linker;
 
+/// The context for the PVQ executor.
 pub trait PvqExecutorContext {
+    /// The user data.
     type UserData;
+    /// The user error.
     type UserError;
+    /// Registers the host functions.
     fn register_host_functions(&mut self, linker: &mut Linker<Self::UserData, Self::UserError>);
+    /// Returns a mutable reference to the user data.
     fn data(&mut self) -> &mut Self::UserData;
 }

pvq-executor/src/error.rs

@@ -1,20 +1,23 @@
 use pvq_primitives::PvqError;
+/// The error type for the PVQ executor.
 #[derive(Debug, thiserror::Error)]
 pub enum PvqExecutorError<UserError> {
+    /// The program format is invalid.
     #[error("Invalid PVQ program format")]
     InvalidProgramFormat,
+    /// A memory access error occurred.
     #[error("Memory access error: {0}")]
     MemoryAccessError(polkavm::MemoryAccessError),
-    // Extract from the PVM CallError
+    /// A trap occurred during execution.
     #[error("Trap")]
     Trap,
-    // Extract from the PVM CallError
+    /// Not enough gas to execute the program.
     #[error("Not enough gas")]
     NotEnoughGas,
-    // Usually a custom error type from the extension system definition
+    /// A user-defined error occurred.
     #[error("User error: {0}")]
     User(UserError),
-    // Other errors directly from the PVM
+    /// An other error from the PolkaVM occurred.
     #[error("Other PVM error: {0}")]
     OtherPvmError(polkavm::Error),
 }

pvq-executor/src/executor.rs

@@ -4,16 +4,25 @@ use polkavm::{Config, Engine, Linker, Module, ModuleConfig, ProgramBlob};
 use crate::context::PvqExecutorContext;
 use crate::error::PvqExecutorError;
 
+/// The result of a PVQ execution.
 type PvqExecutorResult<UserError> = Result<Vec<u8>, PvqExecutorError<UserError>>;
+/// The gas limit for a PVQ execution.
 type GasLimit = Option<i64>;
 
+/// The PVQ executor.
 pub struct PvqExecutor<Ctx: PvqExecutorContext> {
     engine: Engine,
     linker: Linker<Ctx::UserData, Ctx::UserError>,
     context: Ctx,
 }
 
 impl<Ctx: PvqExecutorContext> PvqExecutor<Ctx> {
+    /// Creates a new PVQ executor.
+    ///
+    /// # Arguments
+    ///
+    /// * `config`: The PolkaVM configuration.
+    /// * `context`: The PVQ executor context.
     pub fn new(config: Config, mut context: Ctx) -> Self {
         let engine = Engine::new(&config).unwrap();
         let mut linker = Linker::<Ctx::UserData, Ctx::UserError>::new();
@@ -26,6 +35,17 @@ impl<Ctx: PvqExecutorContext> PvqExecutor<Ctx> {
         }
     }
 
+    /// Executes a PVQ program.
+    ///
+    /// # Arguments
+    ///
+    /// * `program`: The PVQ program to execute.
+    /// * `args`: The arguments to pass to the program.
+    /// * `gas_limit`: The gas limit for the execution.
+    ///
+    /// # Returns
+    ///
+    /// A tuple containing the result of the execution and the remaining gas.
     pub fn execute(
         &mut self,
         program: &[u8],

pvq-executor/src/lib.rs

@@ -1,3 +1,4 @@
+//! The PVQ executor.
 #![cfg_attr(not(feature = "std"), no_std)]
 
 extern crate alloc;