u128 to i128, and doc improvements (#329)

* u128 to i128 * doc improvements * remove instance ttl extension

Author: ozgunozerk

examples/nft-royalties/src/contract.rs

@@ -49,7 +49,7 @@ impl ExampleContract {
  token_id
  }
 
- pub fn get_royalty_info(e: &Env, token_id: u32, sale_price: u128) -> (Address, u128) {
+ pub fn get_royalty_info(e: &Env, token_id: u32, sale_price: i128) -> (Address, i128) {
  Base::royalty_info(e, token_id, sale_price)
  }
 }
@@ -83,7 +83,7 @@ impl NonFungibleRoyalties for ExampleContract {
  Base::remove_token_royalty(e, token_id);
  }
 
- fn royalty_info(e: &Env, token_id: u32, sale_price: u128) -> (Address, u128) {
+ fn royalty_info(e: &Env, token_id: u32, sale_price: i128) -> (Address, i128) {
  Base::royalty_info(e, token_id, sale_price)
  }
 }

packages/tokens/non-fungible/src/extensions/royalties/mod.rs

@@ -12,15 +12,25 @@ use soroban_sdk::{Address, Env, Symbol};
 /// trait is designed to be used in conjunction with the `NonFungibleToken`
 /// trait.
 ///
-/// This implementation follows the ERC2981 standard for royalties, allowing:
-/// - Setting global royalties for the entire collection
-/// - Setting per-token royalties that override the global setting
+/// This implementation is inspired by the ERC2981 standard for royalties, and
+/// additionally, it allows:
+/// - Get the royalty info for a token
+/// - Set the global default royalty for the entire collection
+/// - Set per-token royalties that override the global setting
+/// - Remove per-token royalties to fall-back to the global royalty set for the
+/// contract
 ///
 /// `storage.rs` file of this module provides the `NonFungibleRoyalties` trait
 /// implementation.
 ///
 /// # Notes
 ///
+/// In most marketplaces, royalty calculations are done in amounts of fungible
+/// tokens. For example, if an NFT is sold for 10000 USDC and royalty is 10%,
+/// 1000 USDC goes to the creator. To preserve the compatibility across
+/// Non-Fungible and Fungible tokens, we are using `i128` instead of `u128` for
+/// the `sale_price`, due to SEP-41.
+///
 /// `#[contractimpl]` macro requires even the default implementations to be
 /// present under its scope. To avoid confusion, we do not provide the default
 /// implementations here, but we are providing a macro that generates them.
@@ -109,7 +119,7 @@ pub trait NonFungibleRoyalties: NonFungibleToken {
  /// * data - `[]`
  fn remove_token_royalty(e: &Env, token_id: u32, operator: Address);
 
- /// Returns `(Address, u128)` - A tuple containing the receiver address and
+ /// Returns `(Address, i128)` - A tuple containing the receiver address and
  /// the royalty amount.
  ///
  /// # Arguments
@@ -123,7 +133,7 @@ pub trait NonFungibleRoyalties: NonFungibleToken {
  ///
  /// * [`crate::NonFungibleTokenError::NonExistentToken`] - If the token does
  /// not exist.
- fn royalty_info(e: &Env, token_id: u32, sale_price: u128) -> (Address, u128);
+ fn royalty_info(e: &Env, token_id: u32, sale_price: i128) -> (Address, i128);
 }
 
 // ################## EVENTS ##################

packages/tokens/non-fungible/src/extensions/royalties/storage.rs

@@ -154,7 +154,7 @@ impl Base {
  /// * [`NonFungibleTokenError::NonExistentToken`] - If the token does not
  /// exist.
  /// * refer to [`Base::owner_of`] errors.
- pub fn royalty_info(e: &Env, token_id: u32, sale_price: u128) -> (Address, u128) {
+ pub fn royalty_info(e: &Env, token_id: u32, sale_price: i128) -> (Address, i128) {
  // Verify token exists by checking owner
  let _ = Base::owner_of(e, token_id);
 
@@ -166,15 +166,14 @@ impl Base {
  OWNER_TTL_THRESHOLD,
  OWNER_EXTEND_AMOUNT,
  );
- let royalty_amount = sale_price * royalty_info.basis_points as u128 / 10000;
+ let royalty_amount = sale_price * royalty_info.basis_points as i128 / 10000;
  return (royalty_info.receiver, royalty_amount);
  }
 
  // Fall back to default royalty if no token-specific royalty is set
  let default_key = NFTRoyaltiesStorageKey::DefaultRoyalty;
  if let Some(royalty_info) = e.storage().instance().get::<_, RoyaltyInfo>(&default_key) {
- e.storage().instance().extend_ttl(OWNER_TTL_THRESHOLD, OWNER_EXTEND_AMOUNT);
- let royalty_amount = sale_price * royalty_info.basis_points as u128 / 10000;
+ let royalty_amount = sale_price * royalty_info.basis_points as i128 / 10000;
  return (royalty_info.receiver, royalty_amount);
  }