feat(near-contract-standards): NEP-199 - Non-Fungible Token Royalties and Payouts

.github/workflows/test.yml

@@ -23,10 +23,11 @@ jobs:
           toolchain: ${{ matrix.toolchain }}
           default: true
           target: wasm32-unknown-unknown
-      - name: downgrade `anstyle`,`anstyle-parse`,`clap`,`clap_lex` crates to support older Rust toolchain
+      - name: downgrade `anstyle`,`anstyle-parse`,`anstyle-query`,`clap`,`clap_lex` crates to support older Rust toolchain
         if: matrix.toolchain == '1.69.0' 
         run: |
           cargo update -p anstyle --precise 1.0.2
+          cargo update -p anstyle-query --precise 1.0.0
           cargo update -p anstyle-parse --precise 0.2.1
           cargo update -p clap --precise 4.3.24
           cargo update -p clap_lex --precise 0.5.0

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+- **BREAKING** Added [NEP-199 - Non-Fungible Token Royalties and Payouts](https://github.com/willemneal/NEPs/blob/18828873648eff1a2e8464db234aefd70918b3e0/neps/nep-0199.md) implementation. This
+will need a state migration in case of upgrade for any contracts using NFT of previous versions due to an extra field.
+
 ## [5.0.0-alpha.1](https://github.com/near/near-sdk-rs/compare/4.1.1...near-sdk-v5.0.0-alpha.1) - 2023-11-18
 
 ### Added

examples/non-fungible-token/nft/src/lib.rs

@@ -23,7 +23,8 @@ use near_contract_standards::non_fungible_token::enumeration::NonFungibleTokenEn
 use near_contract_standards::non_fungible_token::metadata::{
     NFTContractMetadata, NonFungibleTokenMetadataProvider, TokenMetadata, NFT_METADATA_SPEC,
 };
-use near_contract_standards::non_fungible_token::NonFungibleToken;
+use near_contract_standards::non_fungible_token::payout::Payout;
+use near_contract_standards::non_fungible_token::{NonFungibleToken, NonFungibleTokenPayout};
 use near_contract_standards::non_fungible_token::{Token, TokenId};
 use near_sdk::borsh::{BorshDeserialize, BorshSerialize};
 use near_sdk::collections::LazyOption;
@@ -51,6 +52,7 @@ enum StorageKey {
     TokenMetadata,
     Enumeration,
     Approval,
+    Royalties,
 }
 
 #[near_bindgen]
@@ -84,6 +86,7 @@ impl Contract {
                 Some(StorageKey::TokenMetadata),
                 Some(StorageKey::Enumeration),
                 Some(StorageKey::Approval),
+                Some(StorageKey::Royalties),
             ),
             metadata: LazyOption::new(StorageKey::Metadata, Some(&metadata)),
         }
@@ -214,6 +217,34 @@ impl NonFungibleTokenEnumeration for Contract {
     }
 }
 
+#[near_bindgen]
+impl NonFungibleTokenPayout for Contract {
+    #[allow(unused_variables)]
+    fn nft_payout(&self, token_id: String, balance: U128, max_len_payout: Option<u32>) -> Payout {
+        self.tokens.nft_payout(token_id, balance, max_len_payout)
+    }
+
+    #[payable]
+    fn nft_transfer_payout(
+        &mut self,
+        receiver_id: AccountId,
+        token_id: String,
+        approval_id: Option<u64>,
+        memo: Option<String>,
+        balance: U128,
+        max_len_payout: Option<u32>,
+    ) -> Payout {
+        self.tokens.nft_transfer_payout(
+            receiver_id,
+            token_id,
+            approval_id,
+            memo,
+            balance,
+            max_len_payout,
+        )
+    }
+}
+
 #[near_bindgen]
 impl NonFungibleTokenMetadataProvider for Contract {
     fn nft_metadata(&self) -> NFTContractMetadata {
@@ -331,6 +362,84 @@ mod tests {
         }
     }
 
+    #[test]
+    fn test_transfer_payout() {
+        let mut context = get_context(accounts(0));
+        testing_env!(context.build());
+        let mut contract = Contract::new_default_meta(accounts(0).into());
+
+        testing_env!(context
+            .storage_usage(env::storage_usage())
+            .attached_deposit(MINT_STORAGE_COST)
+            .predecessor_account_id(accounts(0))
+            .build());
+        let token_id = "0".to_string();
+        contract.nft_mint(token_id.clone(), accounts(0), sample_token_metadata());
+
+        testing_env!(context
+            .storage_usage(env::storage_usage())
+            .attached_deposit(NearToken::from_yoctonear(1))
+            .predecessor_account_id(accounts(0))
+            .build());
+
+        let payout = contract.nft_transfer_payout(
+            accounts(1),
+            token_id.clone(),
+            None,
+            None,
+            U128::from(1),
+            None,
+        );
+
+        let mut expected_payout = HashMap::new();
+        expected_payout.insert(accounts(0), U128::from(1));
+
+        assert_eq!(payout.payout, expected_payout);
+
+        testing_env!(context
+            .storage_usage(env::storage_usage())
+            .account_balance(env::account_balance())
+            .is_view(true)
+            .attached_deposit(NearToken::from_near(0))
+            .build());
+
+        if let Some(token) = contract.nft_token(token_id.clone()) {
+            assert_eq!(token.token_id, token_id);
+            assert_eq!(token.owner_id, accounts(1));
+            assert_eq!(token.metadata.unwrap(), sample_token_metadata());
+            assert_eq!(token.approved_account_ids.unwrap(), HashMap::new());
+        } else {
+            panic!("token not correctly created, or not found by nft_token");
+        }
+    }
+
+    #[test]
+    fn test_payout() {
+        let mut context = get_context(accounts(0));
+        testing_env!(context.build());
+        let mut contract = Contract::new_default_meta(accounts(0).into());
+
+        testing_env!(context
+            .storage_usage(env::storage_usage())
+            .attached_deposit(MINT_STORAGE_COST)
+            .predecessor_account_id(accounts(0))
+            .build());
+        let token_id = "0".to_string();
+        contract.nft_mint(token_id.clone(), accounts(0), sample_token_metadata());
+
+        testing_env!(context
+            .storage_usage(env::storage_usage())
+            .predecessor_account_id(accounts(0))
+            .build());
+
+        let payout = contract.nft_payout(token_id, U128::from(1), None);
+
+        let mut expected_payout = HashMap::new();
+        expected_payout.insert(accounts(0), U128::from(1));
+
+        assert_eq!(payout.payout, expected_payout);
+    }
+
     #[test]
     fn test_approve() {
         let mut context = get_context(accounts(0));

examples/non-fungible-token/tests/workspaces/main.rs

@@ -1,4 +1,5 @@
 mod test_approval;
 mod test_core;
 mod test_enumeration;
+mod test_payout;
 mod utils;

examples/non-fungible-token/tests/workspaces/test_core.rs

@@ -191,6 +191,7 @@ async fn simulate_transfer_call_receiver_panics_and_nft_resolve_transfer_produce
         .deposit(ONE_YOCTO)
         .transact()
         .await?;
+
     assert!(res.is_failure());
 
     // Prints no logs

examples/non-fungible-token/tests/workspaces/test_enumeration.rs

@@ -97,12 +97,8 @@ async fn simulate_enum_nft_supply_for_owner() -> anyhow::Result<()> {
     let (nft_contract, alice, _, _) = init(&worker).await?;
 
     // Get number from account with no NFTs
-    let owner_num_tokens: U128 = nft_contract
-        .call("nft_supply_for_owner")
-        .args_json((alice.id(),))
-        .view()
-        .await?
-        .json()?;
+    let owner_num_tokens: U128 =
+        nft_contract.call("nft_supply_for_owner").args_json((alice.id(),)).view().await?.json()?;
     assert_eq!(owner_num_tokens, U128::from(0));
 
     let owner_num_tokens: U128 = nft_contract

examples/non-fungible-token/tests/workspaces/test_payout.rs

@@ -0,0 +1,61 @@
+use crate::utils::{init, TOKEN_ID};
+use near_contract_standards::non_fungible_token::Token;
+use near_sdk::json_types::U128;
+use near_sdk::NearToken;
+
+const ONE_YOCTO: NearToken = NearToken::from_yoctonear(1);
+
+#[tokio::test]
+async fn simulate_payout() -> anyhow::Result<()> {
+    let worker = near_workspaces::sandbox().await?;
+    let (nft_contract, alice, _, _) = init(&worker).await?;
+
+    let res = nft_contract
+        .call("nft_payout")
+        .args_json((TOKEN_ID, U128::from(1), Option::<u32>::None))
+        .max_gas()
+        .transact()
+        .await?;
+    assert!(res.is_success());
+
+    // A single NFT transfer event should have been logged:
+    assert_eq!(res.logs().len(), 0);
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn nft_transfer_payout() -> anyhow::Result<()> {
+    let worker = near_workspaces::sandbox().await?;
+    let (nft_contract, alice, _, _) = init(&worker).await?;
+
+    let token =
+        nft_contract.call("nft_token").args_json((TOKEN_ID,)).view().await?.json::<Token>()?;
+    assert_eq!(token.owner_id.to_string(), nft_contract.id().to_string());
+
+    let res = nft_contract
+        .call("nft_transfer_payout")
+        .args_json((
+            alice.id(),
+            TOKEN_ID,
+            Option::<u64>::None,
+            Some("simple transfer".to_string()),
+            U128::from(1),
+            Option::<u32>::None,
+        ))
+        .max_gas()
+        .deposit(ONE_YOCTO)
+        .transact()
+        .await?;
+
+    assert!(res.is_success());
+
+    // A single NFT transfer event should have been logged:
+    assert_eq!(res.logs().len(), 1);
+
+    let token =
+        nft_contract.call("nft_token").args_json((TOKEN_ID,)).view().await?.json::<Token>()?;
+    assert_eq!(token.owner_id.to_string(), alice.id().to_string());
+
+    Ok(())
+}

near-contract-standards/src/non_fungible_token/core/core_impl.rs

@@ -4,6 +4,7 @@ use crate::non_fungible_token::core::resolver::ext_nft_resolver;
 use crate::non_fungible_token::core::NonFungibleTokenCore;
 use crate::non_fungible_token::events::{NftMint, NftTransfer};
 use crate::non_fungible_token::metadata::TokenMetadata;
+use crate::non_fungible_token::payout::Royalties;
 use crate::non_fungible_token::token::{Token, TokenId};
 use crate::non_fungible_token::utils::{refund_approved_account_ids, refund_deposit_to_account};
 use near_sdk::borsh::{BorshDeserialize, BorshSerialize};
@@ -49,6 +50,7 @@ pub struct NonFungibleToken {
     // required by approval extension
     pub approvals_by_id: Option<LookupMap<TokenId, HashMap<AccountId, u64>>>,
     pub next_approval_id_by_id: Option<LookupMap<TokenId, u64>>,
+    pub royalties: Option<Royalties>,
 }
 
 #[derive(BorshStorageKey, BorshSerialize)]
@@ -58,18 +60,20 @@ pub enum StorageKey {
 }
 
 impl NonFungibleToken {
-    pub fn new<Q, R, S, T>(
+    pub fn new<Q, R, S, T, Y>(
         owner_by_id_prefix: Q,
         owner_id: AccountId,
         token_metadata_prefix: Option<R>,
         enumeration_prefix: Option<S>,
         approval_prefix: Option<T>,
+        royalties_prefix: Option<Y>,
     ) -> Self
     where
         Q: IntoStorageKey,
         R: IntoStorageKey,
         S: IntoStorageKey,
         T: IntoStorageKey,
+        Y: IntoStorageKey,
     {
         let (approvals_by_id, next_approval_id_by_id) = if let Some(prefix) = approval_prefix {
             let prefix: Vec<u8> = prefix.into_storage_key();
@@ -89,6 +93,7 @@ impl NonFungibleToken {
             tokens_per_owner: enumeration_prefix.map(LookupMap::new),
             approvals_by_id,
             next_approval_id_by_id,
+            royalties: royalties_prefix.map(|prefix| Royalties::new(prefix)),
         };
         this.measure_min_token_storage_cost();
         this

near-contract-standards/src/non_fungible_token/mod.rs

@@ -12,6 +12,9 @@ mod macros;
 /// Metadata traits and implementation according to the [NFT enumeration standard](https://nomicon.io/Standards/NonFungibleToken/Metadata.html).
 /// This covers both the contract metadata and the individual token metadata.
 pub mod metadata;
+
+pub mod payout;
+
 /// The Token struct for the non-fungible token.
 mod token;
 pub use self::token::{Token, TokenId};
@@ -26,5 +29,6 @@ pub use self::approval::NonFungibleTokenApproval;
 pub use self::core::NonFungibleToken;
 pub use self::core::NonFungibleTokenResolver;
 pub use self::enumeration::NonFungibleTokenEnumeration;
+pub use self::payout::NonFungibleTokenPayout;
 
 pub mod events;