finize fungible trait and storage

contracts/token/fungible/src/fungible.rs

@@ -2,73 +2,68 @@ use soroban_sdk::{contractclient, contracterror, symbol_short, Address, Env};
 
 #[contractclient(name = "FungibleTokenClient")]
 pub trait FungibleToken {
-    /// Returns the number of tokens a `spender` is allowed to spend on behalf
-    /// of an `owner` through [`transfer_from()`]. Defaults to `0`.
+    /// Returns the total amount of tokens in circulation.
     ///
     /// # Arguments
+    /// * `e` - Access to the Soroban environment.
+    fn total_supply(e: &Env) -> i128;
+
+    /// Returns the amount of tokens held by `account`.
     ///
-    /// * `e` - Access to Soroban environment.
-    /// * `owner` - The address holding the tokens.
-    /// * `spender` - The address authorized to spend the tokens.
+    /// # Arguments
+    /// * `e` - Access to the Soroban environment.
+    /// * `account` - The address for which the balance is being queried.
     ///
     /// # Notes
     ///
-    /// We recommend using the [`crate::storage::allowance()`] function from
+    /// We recommend using the [`crate::storage::balance()`] function from
     /// the `storage` module when implementing this function.
-    fn allowance(e: Env, owner: Address, spender: Address) -> i128;
+    fn balance(e: Env, account: Address) -> i128;
 
-    /// Sets the number of tokens a `spender` is allowed to spend on behalf of
-    /// an `owner`. Overrides any existing allowance set between `spender` and
-    /// `owner`.
+    /// Transfers a `value` amount of tokens from `owner` to `to`.
     ///
     /// # Arguments
     ///
     /// * `e` - Access to Soroban environment.
     /// * `owner` - The address holding the tokens.
-    /// * `spender` - The address authorized to spend the tokens.
-    /// * `value` - The number of tokens made available to `spender`.
-    /// * `live_until_ledger` - The ledger number at which the allowance will
-    ///   expire.
+    /// * `to` - The address receiving the transferred tokens.
+    /// * `value` - The value of tokens to be transferred.
     ///
     /// # Errors
     ///
-    /// When trying to set a value for `live_until_ledger` that is lower than
-    /// the current ledger number and greater than `0`, then the error
-    /// [`FungibleTokenError::InvalidLiveUntilLedger`] is thrown.
+    /// * [`FungibleTokenError::InsufficientBalance`] - When attempting to
+    ///   transfer more tokens than `owner` current balance.
     ///
     /// # Events
     ///
-    /// * topics - `["approve", from: Address, spender: Address]`
-    /// * data - `[value: i128, live_until_ledger: u32]`
+    /// * topics - `["transfer", from: Address, to: Address]`
+    /// * data - `[value: i128]`
     ///
     /// # Notes
     ///
-    /// We recommend using the [`crate::storage::approve()`] function from
+    /// We recommend using the [`crate::storage::transfer()`] function from
     /// the `storage` module when implementing this function.
-    fn approve(e: Env, owner: Address, spender: Address, value: i128, live_until_ledger: u32);
+    fn transfer(e: Env, owner: Address, to: Address, value: i128);
 
-    /// Returns the number of tokens held by an `account`. Defaults to `0` if
-    /// no balance is stored.
+    /// Transfers a `value` amount of tokens from `owner` to `to` using the
+    /// allowance mechanism. `value` is then deducted from `spender allowance.
     ///
     /// # Arguments
     ///
     /// * `e` - Access to Soroban environment.
-    /// * `account` - The address for which a balance is being queried.
-    ///
-    /// # Notes
+    /// * `spender` - The address authorizing the transfer, and having its
+    ///   allowance consumed during the transfer.
+    /// * `owner` - The address holding the tokens which will be transferred.
+    /// * `to` - The address receiving the transferred tokens.
+    /// * `value` - The amount of tokens to be transferred.
     ///
-    /// We recommend using the [`crate::storage::balance()`] function from
-    /// the `storage` module when implementing this function.
-    fn balance(e: Env, account: Address) -> i128;
-
-    /// Transfers a `value` number of tokens from `owner` to `to`.
+    /// # Errors
     ///
-    /// # Arguments
+    /// * [`FungibleTokenError::InsufficientBalance`] - When attempting to
+    ///   transfer more tokens than `owner` current balance.
+    /// * [`FungibleTokenError::InsufficientAllowance`] - When attempting to
+    ///   transfer more tokens than `spender` current allowance.
     ///
-    /// * `e` - Access to Soroban environment.
-    /// * `owner` - The address holding the tokens.
-    /// * `to` - The address which will receive the transferred tokens.
-    /// * `value` - The value of tokens to be transferred.
     ///
     /// # Events
     ///
@@ -77,33 +72,52 @@ pub trait FungibleToken {
     ///
     /// # Notes
     ///
-    /// We recommend using the [`crate::storage::transfer()`] function from
+    /// We recommend using the [`crate::storage::transfer_from()`] function from
     /// the `storage` module when implementing this function.
-    fn transfer(e: Env, owner: Address, to: Address, value: i128);
+    fn transfer_from(e: Env, spender: Address, owner: Address, to: Address, value: i128);
 
-    /// Transfers a `value` number of tokens from `owner` to `to` using the
-    /// allowance mechanism. `value` is then deducted from the `spender`
-    /// allowance.
+    /// Returns the amount of tokens a `spender` is allowed to spend on behalf
+    /// of an `owner`.
     ///
     /// # Arguments
     ///
     /// * `e` - Access to Soroban environment.
-    /// * `spender` - The address authorizing the transfer, and having its
-    ///   allowance consumed during the transfer.
-    /// * `owner` - The address holding the tokens which will be transferred.
-    /// * `to` - The address which will receive the transferred tokens.
-    /// * `value` - The number of tokens to be transferred.
+    /// * `owner` - The address holding the tokens.
+    /// * `spender` - The address authorized to spend the tokens.
+    ///
+    /// # Notes
+    ///
+    /// We recommend using the [`crate::storage::allowance()`] function from
+    /// the `storage` module when implementing this function.
+    fn allowance(e: Env, owner: Address, spender: Address) -> i128;
+
+    /// Sets the amount of tokens a `spender` is allowed to spend on behalf of
+    /// an `owner`. Overrides any existing allowance set between `spender` and
+    /// `owner`. # Arguments
+    ///
+    /// * `e` - Access to Soroban environment.
+    /// * `owner` - The address holding the tokens.
+    /// * `spender` - The address authorized to spend the tokens.
+    /// * `value` - The amount of tokens made available to `spender`.
+    /// * `live_until_ledger` - The ledger number at which the allowance
+    ///   expires.
+    ///
+    /// # Errors
+    ///
+    /// * [`FungibleTokenError::InvalidLiveUntilLedger`] - Occurs when
+    ///   attempting to set `live_until_ledger` that is less than the current
+    ///   ledger number and greater than `0`.
     ///
     /// # Events
     ///
-    /// * topics - `["transfer", from: Address, to: Address]`
-    /// * data - `[value: i128]`
+    /// * topics - `["approve", from: Address, spender: Address]`
+    /// * data - `[value: i128, live_until_ledger: u32]`
     ///
     /// # Notes
     ///
-    /// We recommend using the [`crate::storage::transfer_from()`] function from
+    /// We recommend using the [`crate::storage::approve()`] function from
     /// the `storage` module when implementing this function.
-    fn transfer_from(e: Env, spender: Address, owner: Address, to: Address, value: i128);
+    fn approve(e: Env, owner: Address, spender: Address, value: i128, live_until_ledger: u32);
 }
 
 // ################## ERRORS ##################
@@ -124,11 +138,38 @@ pub enum FungibleTokenError {
 
 // ################## EVENTS ##################
 
+/// Emits an event indicating a transfer of tokens.
+///
+/// # Arguments
+///
+/// * `e` - Access to Soroban environment.
+/// * `from` - The address holding the tokens.
+/// * `to` - The address receiving the transferred tokens.
+/// * `value` - The value of tokens to be transferred.
+///
+/// # Events
+///
+/// * topics - `["transfer", from: Address, to: Address]`
+/// * data - `[value: i128]`
 pub fn emit_transfer(e: &Env, from: &Address, to: &Address, value: i128) {
     let topics = (symbol_short!("transfer"), from, to);
     e.events().publish(topics, value)
 }
 
+/// Emits an event indicating an allowance was granted.
+///
+/// # Arguments
+///
+/// * `e` - Access to Soroban environment.
+/// * `from` - The address holding the tokens.
+/// * `spender` - The address authorized to spend the tokens.
+/// * `value` - The amount of tokens made available to `spender`.
+/// * `live_until_ledger` - The ledger number at which the allowance expires.
+///
+/// # Events
+///
+/// * topics - `["approve", from: Address, spender: Address]`
+/// * data - `[value: i128, live_until_ledger: u32]`
 pub fn emit_approve(
     e: &Env,
     from: &Address,