NFT Enumeration Standard

[chadoh]

This discussion split from the more general discussion in #171. While that was intended to tackle the entire upcoming NFT standard, this discussion aims to only clarify the Enumeration aspect. Below seems to be the current best-guess at what a v1.0.0 standard might look like, based on current discussion in #171 & the NEAR team's best guesses:

Summary

Standard interfaces for counting & fetching tokens, for an entire NFT contract or for a given owner.

Motivation

Apps such as marketplaces and wallets need a way to show all tokens owned by a given account and to show statistics about all tokens for a given contract. This extension provides a standard way to do so.

While some NFT contracts may forego this extension to save storage costs, this requires apps to have custom off-chain indexing layers. This makes it harder for apps to integrate with such NFTs. Apps which integrate only with NFTs that use the Enumeration extension do not even need a server-side component at all, since they can retrieve all information they need directly from the blockchain.

Prior art:

• ERC-721's enumeration extension

Interface

The contract must implement the following view methods:

// Returns the total supply of non-fungible tokens as a string representing an
// unsigned 128-bit integer to avoid JSON number limit of 2^53.
function nft_total_supply(): string {}

// Get a list of all tokens
//
// Arguments:
// * `from_index`: a string representing an unsigned 128-bit integer,
//    representing the starting index of tokens to return
// * `limit`: the maximum number of tokens to return
//
// Returns an array of Token objects, as described in Core standard
function nft_tokens(
  from_index: string|null, // default: "0"
  limit: number|null, // default: unlimited (could fail due to gas limit)
): Token[] {}

// Get number of tokens owned by a given account
//
// Arguments:
// * `account_id`: a valid NEAR account
//
// Returns the number of non-fungible tokens owned by given `account_id` as
// a string representing the value as an unsigned 128-bit integer to avoid JSON
// number limit of 2^53.
function nft_supply_for_owner(
  account_id: string,
): string {}

// Get list of all tokens owned by a given account
//
// Arguments:
// * `account_id`: a valid NEAR account
// * `from_index`: a string representing an unsigned 128-bit integer,
//    representing the starting index of tokens to return
// * `limit`: the maximum number of tokens to return
//
// Returns a paginated list of all tokens owned by this account
function nft_tokens_for_owner(
  account_id: string,
  from_index: string|null, // default: 0
  limit: number|null, // default: unlimited (could fail due to gas limit)
): Token[] {}

[thor314]

Rust-translated:

/// Ref:
/// https://github.com/near/NEPs/blob/master/specs/Standards/NonFungibleToken/Enumeration.md
pub trait NonFungibleContractEnumeration {
  /// Returns the total supply of non-fungible tokens as a String representing an
  /// unsigned 128-bit integer to avoid JSON number limit of 2^53.
  fn nft_total_supply(&self) -> U64;

  /// Get a list of all tokens
  ///
  /// Arguments:
  /// * `from_index`: a String representing an unsigned 128-bit integer,
  ///    representing the starting index of tokens to return
  /// * `limit`: the maximum number of tokens to return
  ///
  /// Returns an array of Token objects, as described in Core standard
  fn nft_tokens(
    &self,
    from_index: Option<U64>, // default: "0"
    limit: Option<U64>,      // default: = self.nft_total_supply()
  ) -> Vec<Token>;

  /// Get number of tokens owned by a given account
  ///
  /// Arguments:
  /// * `account_id`: a valid NEAR account
  ///
  /// Returns the number of non-fungible tokens owned by given `account_id` as
  /// a String representing the value as an unsigned 128-bit integer to avoid JSON
  /// number limit of 2^53.
  fn nft_supply_for_owner(&self, account_id: String) -> U64;

  // temp
  fn nft_tokens_for_owner_set(&self, account_id: String) -> Vec<TokenId>;

  /// Get list of all tokens owned by a given account
  ///
  /// Arguments:
  /// * `account_id`: a valid NEAR account
  /// * `from_index`: a String representing an unsigned 128-bit integer,
  ///    representing the starting index of tokens to return
  /// * `limit`: the maximum number of tokens to return
  ///
  /// Returns a paginated list of all tokens owned by this account
  fn nft_tokens_for_owner(
    &self,
    account_id: String,
    from_index: Option<U64>, // default: 0
    limit: Option<U64>,      // default: nft_supply_for_owner(account_id)
  ) -> Vec<TokenId>;
}

Some of the outstanding comments I have on the spec:

• Several instances where the spec uses a String or a Number, I suggest instead returning U64.
• It seems unlikely to me that any contract will mint N>2^64 (~10^19) tokens, so U128 is overkill
• It seems reasonable that nft_tokens_for_owner should return an array of TokenIds, which is cheaper than returning an array of Tokens, and makes more sense in any case
• nft_tokens_for_owner, as spec'ed requires a mapping from account_ids to the collection of token_ids owned by the given account. This could be implemented either as:

  pub tokens_per_owner: LookupMap<AccountId, UnorderedSet<TokenId>>,
//or
  pub tokens_per_owner: LookupMap<AccountId, Vector<TokenId>>,

If the former is used, it's not possible to index into the UnorderedSet in a reasonable way. Therefore, the spec is implicitly forcing the latter implementation. This should be explicit, or if this is unintended, the API for nft_tokens_for_owner should be modified.

[thor314]

A sample implementation

impl NonFungibleContractEnumeration for MintbaseStore {
  fn nft_total_supply(&self) -> U64 {
    self.tokens_minted.into()
  }

  fn nft_tokens(
    &self,
    from_index: Option<U64>, // default: "0"
    limit: Option<U64>,      // default: = self.nft_total_supply()
  ) -> Vec<Token> {
    let from_index: u64 = from_index.map(|i| i.into()).unwrap_or(0);
    let limit: u64 = limit
      .map(|limit| {
        let limit: u64 = limit.into();
        assert!(limit <= self.nft_total_supply().into());
        limit
      })
      .unwrap_or_else(|| self.nft_total_supply().into());

    (from_index..limit)
      .into_iter()
      .map(|token_id| self.get_token(token_id))
      .collect()
  }

  fn nft_supply_for_owner(&self, account_id: String) -> U64 {
    self
      .tokens_per_owner
      .get(&account_id)
      .map(|v| v.len())
      .unwrap_or(0)
      .into()
  }

  /// A non-indexed implementation. `from_index` and `limit are removed, so as
  /// to support the:
  ///
  /// `tokens_per_owner: LookupMap<AccountId, UnorderedSet<TokenId>>`
  ///
  /// type. They may be used in an implementation if the type is instead:
  ///
  /// `tokens_per_owner: LookupMap<AccountId, Vector<TokenId>>`
  fn nft_tokens_for_owner_set(&self, account_id: String) -> Vec<TokenId> {
    self
      .tokens_per_owner
      .get(&account_id)
      .expect("no tokens")
      .iter()
      .collect()
  }

  // Or else, as spec'ed:
  fn nft_tokens_for_owner(
    &self,
    account_id: String,
    from_index: Option<U64>, // default: 0
    limit: Option<U64>,      // default: nft_supply_for_owner(account_id)
  ) -> Vec<TokenId> {
    let from_index: u64 = from_index.map(|i| i.into()).unwrap_or(0);
    let vector = self
      .tokens_per_owner
      .get(&account_id)
      .unwrap_or_else(|| env::panic(b"none"));
    let limit: u64 = limit
      .map(|limit| {
        let limit: u64 = limit.into();
        assert!(limit <= vector.len());
        limit
      })
      .unwrap_or_else(|| self.nft_supply_for_owner(account_id.to_string()).into());

    todo!();
    // (from_index..limit)
    //   .into_iter()
    //   .map(|index| vector[index])
    //   .collect()
  }
}

[zahhar]

I agree that nft_tokens_for_owner() shoulkd return list of TokenIds only.

Then we need nft_token() method, or, probably, nft_metadata() method to obtain information about individual TokenId, and that one will return OwnerAccountId + the Metadata.

[thor314]

yep, agree. nft_metadata is a method we've implemented such that tokens with copies (eg, 5 coffee nfts), store their metadata in a lookup map on the contract, not on the nft itself
pub token_metadata: LookupMap<u64, (u16, TokenMetadata)>,
where the u16 is the number of copies, decremented when one of the copies is burned, or dropped when the last copy is burnt

[chadoh]

nft_metadata should return contract-level metadata, as per the currently-published standard.

I'm so far unconvinced that nft_tokens_for_owner should return IDs instead of Token objects/structs. Two main reasons:

1. nft_tokens_for_owner is a view method, so it costs nothing for the person calling it.
2. Probably 90+% of the time, apps will want to get full tokens, not just IDs. So if nft_tokens_for_owner returns IDs and then the app needs to loop through each and call nft_token, we'll introduce annoying N+1 async complexity into almost every app.

[zahhar]

Colleagues, could you please help me to understand what method nft_total_supply() actually returns? Is it a currently circulating supply of all NFTs minted within the given contract? So when new NFT gets minted → value increases, and when burned → decreses, and when NFT just changes the owner → remains still? Is it a correct understanding?

[chadoh]

Yes, that is the correct understanding.