Native non-fungible token standard

[alexytsu]

To complement the existing fungible-token standard (FRC-46), this is a proposal for a non-fungible token standard for native actors.

Draft FIP has been proposed https://github.com/filecoin-project/FIPs/pull/519/files

Non-Fungible Token Standard

Simple Summary

A standard interface for native actor non-fungible tokens (NFTs).

Abstract

This proposal provides a standard API for the implementation of non-fungible
tokens (NFTs) as FVM native actors. The proposal learns from NFT standards
developed for other blockchain ecosystems, being heavily inspired by
ERC-721. However, as a design goal,
this proposal aims to complement the existing fungible token interface described
in FRC-0046. As such
it brings along equivalent specifications for:

• Standard token/name/symbol/supply/balance queries
• Standard allowance protocol for delegated control, but with an API robust to
  front-running
• Mandatory universal receiver hooks for incoming tokens

The interface has been designed with gas-optimisations in mind and hence methods
support batch-operations where practical.

Change Motivation

The concept of a non-fungible token is widely established in other blockchains.
As on other blockchains, a complementary NFT standard to FRC-0046 allows the
ownership of uniquely identifiable assets to be tracked on-chain. The Filecoin
ecosystem will benefit from a standard API implemented by these actors. A
standard permits easy building of UIs, wallets, tools, and higher level
applications on top of a variety of tokens representing different assets.

Specification

Methods and types are described with a Rust-like pseudocode. All parameters and
return types are IPLD types in a CBOR tuple encoding.

Methods are to be dispatched according to the calling convention described in
FRC-0042.

Interface

An actor implementing a FRC-00XX token must provide the following methods.

type TokenID = u64;

/// A descriptive name for the collection of NFTs in this actor
fn Name() -> String

/// An abbreviated (ticker) name for the NFT collection
fn Symbol() -> String

/// Returns the total number of tokens in this collection
/// Must be non-negative
/// Must equal the balance of all adresses
/// Should equal the sum of all minted tokens less tokens burnt
fn TotalSupply() -> u64

/// Returns a link that resolves to the metadata for a particular token
fn MetadataID(tokenID: TokenID) -> String

/// Returns the balance of an address which is the number of unique NFTs held
/// Must be non-negative
fn BalanceOf(owner: Address) -> String

/// Returns the f0 ID-address that owns the specified token
fn OwnerOf(tokenID: TokenID) -> ActorID

/// Transfers tokens from caller to the specified address
/// Each token specified must exist and be owned by the caller
/// The entire batch of transfers aborts if any of the specified tokens does not meet the criteria
/// Transferring to the caller must be treated as a normal transfer
/// Returns the resulting balances for the from and to addresses
/// The operatorData is passed through to the receiver hook directly
///
/// Tokens that were successfully transferred are returned along with the new balances of the sending and receiving addresses
fn Transfer({to: Address, tokenIDs: TokenID[], operatorData: Bytes})
  -> {fromBalance: u64, toBalance: u64, tokens: TokenID[]}

/// Transfers tokens to the specified address with the caller acting as an operator
/// Each token specified must exist and the caller must be authorised to transfer it. The caller is considered authorised by being an approved operator on the token-id or by being an approved operator on the account that owns the token.
/// The entire batch of transfers aborts if any of the specified tokens does not meet the above criteria
/// Transferring to the owner must be treated as a normal transfer
/// Returns the resulting balance for the to address
/// The operatorData is passed through to the receiver hook directly
///
/// Returns tokens that were successfully transferred are returned along with the new balance of the receiving address
fn TransferFrom({to: Address, tokenIDs: TokenID[], operatorData: Bytes})
  -> {toBalance: u64, tokens: TokenID[]}

/// Authorizes an address as the specified operator for a set of tokens
/// The method returns the IDs of tokens that were succesfully approved for the operator
fn Approve({operator: Address, tokenIDs: TokenID[]}) -> TokenID[]

/// Revokes an address as an authorized operator for a set of tokens
/// Tokens that are not owned by the caller are ignored
///
/// Returns the list of IDs that were succesfully revoked
fn RevokeApproval({operator: Address, tokenIDs: TokenID[]}) -> TokenID[]

/// Returns whether an address is an approved operator for a particular set of tokens
/// The owner of a token is implicitly considered as a valid operator of that token
fn IsApprovedFor({operator: Address, tokenIDs: TokenID[]}) -> bool[]

/// Authorizes the specified address as an operator for any token (including future tokens) that are owned by the caller's address
fn ApproveForAll({operator: Address}) -> ()

/// Returns whether an address is an authorized operator for another address
/// Addresses are not reflexive operators on themselves
fn IsApprovedForAll({operator: Address, owner: Address}) -> bool

/// Revokes an address as an authorized operator for the calling address
fn RevokeApprovalForAll({operator: Address}) -> ()

/// Burns the specified tokens where the caller is the owner
/// The entire burn operation aborts if any of the tokens is not owned by the caller
///
/// Returns the resulting balance of the caller's address
fn Burn({tokenIDs: TokenID[]}) -> u64;

/// Burns the specified tokens where the caller is an approved operator
/// The entire burn operation aborts if the caller is not an approved operator on any of the tokens
fn BurnFrom({tokenIDs: TokenID[]}) -> ();

Receiver Interface

An actor must implement a receiver hook to receive NFTs. The receiver hook is
defined in FRC-0046 and must not abort when handling an incoming token. When
transferring batch of tokens, the receiver hook is invoked once meaning the
entire set of NFTs is either accepted or rejected (by aborting).

/// Type of the payload accompanying the receiver hook for a FRCXX NFT.
struct FRCXXTokensReceived {
    // The tokens being transferred
    tokenIDs: TokenID[],
    // The address to which tokens were credited (which will match the hook receiver)
    to: Address,
    // The actor which initiated the mint or transfer
    operator: Address,
    // Arbitrary data provided by the operator when initiating the transfer
    operatorData: Bytes,
    // Arbitrary data provided by the token actor
    tokenData: Bytes,
}

/// Receiver hook type value for an FRC-00XX token
const FRCXXTokenType = frc42_hash("FRCXX")

// Invoked by a NFT actor after transfer of tokens to the receiver’s address.
// The NFT collection state must be persisted such that the receiver will observe the new balances.
// To reject the transfer, this hook must abort.
fn Receive({type: uint32, payload: []byte})

Behaviour

Universal receiver hook

The NFT collection must invoke the receiver hook method on the receiving address
whenever it credits tokens. The type parameter must be FRCXXTokenType and
the payload must be the IPLD-CBOR serialized FRCXXTokensReceived structure.

The attempted credit is only persisted if the receiver hook is implemented and
does not abort. A mint or transfer operation should abort if the receiver hook
does, or in any case must not credit tokens to that address.

Minting

API methods for minting are left unspecified. A newly minted token cannot have
the same ID as an existing token or a token that was previously burned. Minting
must invoke the receiver hook on the receiving address and fail if it aborts.

Transfers

Empty transfers are allowed, including when the from address has zero balance.
An empty transfer must invoke the receiver hook of the to address and abort if
the hook aborts. An empty transfer can thus be used to send messages between
actors in the context of a specific NFT collection.

Operators

Operators can be approved at two separate levels.

Token level operators are approved by the owner of the token via the Approve
method. If an account is an operator on a token, it is permitted to debit (burn
or transfer) that token. An NFT can have many operators at a time, but
transferring the token will revoke approval on all its existing operators.

Account level operators are approved via the ApproveForAll method. If an
owner approves an operator at the account level, that operator has permission to
debit any token belonging to the owner's account. This includes tokens that are
not yet owned by the account at the time of approval.

Addresses

Addresses for receivers and operators must be resolvable to an actor ID.
Balances must only be credited to an actor ID. All token methods must attempt to
resolve addresses provided in parameters to actor IDs. A token should attempt to
initialise an account for any address which cannot be resolved by sending a
zero-value transfer of the native token to the address.

Note that this means that an uninitialized actor-type (f2) address cannot
receive tokens or be authorized as an operator. Future changes to the FVM may
permit initialization of such addresses by sending a message to them, in which
case they should automatically become functional for this standard.

Extensions

An NFT collection may implement other methods for transferring tokens and
managing operators. These must maintain the invariants about supply and
balances, and invoke the receiver hook when crediting tokens.

An NFT collection may implement restrictions on allowances and transfer of
tokens.

Optional Extension - Enumerable NFT

An actor may choose to implement a method to retrieve the list of all
circulating NFTs.

/// Revokes an address as an authorized operator for the calling address
fn ListTokens({minTokenID: TokenID, maxTokenID}) -> TokenID[]

When listing tokens, the NFT actor should return the list of all currently
circulating NFTs in the range [mintokenID, maxTokenID).

Design Rationale

Batching

Methods on this interface accept a list of token_ids. It is up to specific
implementations how duplicates, invalid IDs etc. are handled. The reference
implementation, for example aborts the entire transfer if any of the specified
token IDs are invalid.

However, it may be desirable for some implementations partially succeed for
batch operations. For example, the intent to Revoke operator status on a set
of TokenIDs can succeed even if some of the TokenIDs are burnt or no longer
owned by the caller to promote security. Methods should inform the caller which
TokenIDs were succesfully acted upon in the return. It is recommended to return
an empty list rather than abort when no TokenIDs are valid.

Synergy with fungible tokens

In order for higher synergy with the existing FRC-0046 fungible token standard,
this proposal aims for a conceptually similar interface in terms of balances,
supply and operators. For the same safety reasons described in FRC-0046, this
token standard requires a universal receiver on actors that wish to hold tokens.

This allows easier interactions between fungible tokens and NFTs and opens
possibilities for composition of the the two standards to represent different
structures of ownership such as fractionalized NFTs or semi-fungible tokens.
Instead of encoding such semantics directly into the standard, a minimal
interface is proposed instead to make the primary simple use cases more
efficient and straightforward.

Transfers

There is no technical need to separate the Transfer and TransferFrom
methods. A transfer method could function given only the list of token ids that
the caller wishes to transfer and for each token asserts that:

• The caller is the owner of the token OR
• The caller is an approved operator on the token OR
• The caller is an approved operator on the account that owns the token

However, the authors judge that the benefit of aligning with existing
conventions (FRC-46, ERC-721 etc.) and having separate flows for operators and
token owners will reduce risk of mistakes and unexpected behaviour.

Backwards Compatability

There are no implementatons of NFT collections yet on Filecoin.

Test Cases

Extensive test cases are present in the implementation of this proposal at
https://github.com/helix-onchain/filecoin/tree/main/frcxx_nft.

Security Considerations

Reentrancy

Receiver hooks introduce the possibility of complex call flows, the most
concerning of which might be a malicious receiver that calls back to a token
actor in an attempt to exploit a re-entrancy bug. We expect that one or more
high quality reference implementations of the token state and logic will keep
the vast majority of NFT actors safe. We judge the risk to more complex actors
as lesser than the aggregate risk of losses due to misdirected transfers.

Incentive Considerations

N/A

Product Considerations

??

Implementation

An implementation of this standard is in development at
https://github.com/helix-onchain/filecoin/tree/main/frcxx_nft.

Copyright

Copyright and related rights waived via
CC0.

[FroghubMan]

fn Metadata(tokenID: TokenID) -> String

FVM has the ability of provable storage, which can perform the "mint" operation while verifying that the data is stored in filecoin for a long time. Then matadata will be more expressive than ERC721's TokenUrl, not limited to external url links, but can be directly represented by CID, SVG, JSON, HTML, etc.
I think expand "MetadataID" to "metadata" for a broader meaning.

[anorth]

I think this standard is aiming for the most general NFT API, which should not assume that there's some data asset (like an image) being represented. E.g. an NFT could represent a deposit asset or loan obligation. I concur that we can probably do something better than ERC721's metadata standard, but note that this proposal has omitted any specification of the content of that metadata JSON, which is probably the right thing to do. Another proposal could define schemas for some metadata for certain applications (like data assets).

[anorth]

Thanks @alexytsu!

Regarding the MetadataID, I think we have an opportunity to improve on the status quo in other chains by locking this in as a content identifier, rather than a locator. Should we change the return type to be CID explicitly (which has a defined tag in the CBOR-encoded wire format)? Or can we identify cases where that will be too restrictive? cc @mikeal

[mikeal]

NFT standards vary wildly across different chains and there’s almost nothing consistent across all of them.

The only thing consistent we’ve found is that an NFT has something called “metadata” and that is described as a URI to something that renders as JSON. If you do something else you’ll be the only chain that doesn’t do the one thing every other chain actually does consistently 🤷‍♂️

We developed this spec as a way to get a proper dag-cbor representation without breaking this compatibility https://github.com/nftstorage/ipnft .

If you create NFT’s with our client (nft.storage) we follow that spec, but outside of our own code it isn’t widely adopted. In fact, there’s a few specs out there that try to clean up NFT’s, and none of them are particularly well adopted.

[anorth]

Thanks, sounds like mandating a CID would be shooting outselves in the foot here. But we could add a "should" about using an ipfs:// URL perhaps.

[mikeal]

ya, we tried to get people in the broader NFT ecosystem to use ipfs:// for a while but some marketplaces don’t support it and gateway URLs “just work” so adoption has been slim.

hopefully we’ll have better luck in an IPLD/IPFS native ecosystem 😁

[Stebalien]

Can we mandate a URI/URL?

[anorth]

Transfer semantics are defined to be all-or-nothing for the batch, which I agree with. I think this means that the token IDs are not needed in the return value. The comments about that return value imply that some transfers could fail.

Similar applies to TransferFrom.

By reference to FRC-0046, only the balances are returned, not the transferred amount.

[alexytsu]

I'm more in favour here of all methods allowing partial success/failure. I would propose that the general recommendation should be to abort when any single selected token_id is invalid for the given method. However, there may be use cases where it's impractical to determine success/failure of the operation beforehand and the standard should not be overly restrictive here.

Certainly the reference implementation will fail the entire batch for Burn, BurnFrom, Transfer and TransferFrom. I think there is a net benefit for Approve and Revoke to allow partial success.

[anorth]

For Approve and Revoke, it's not practical to return the full set of approved tokens for the operator (resulting allowance, in FRC-0046 terms), but I don't think returning the same token IDs that were input is useful. We should define that the batch is all-or-nothing.

[anorth]

Ah, sorry. I see in the rationale that these batches are not all-or-nothing. Let's just clarify that in the API spec comments, and then 👍

[anorth]

It looks like we're missing an OwnerOf([]tokenIds) method, which I guess is just an oversight.

[anorth]

It is interesting that the from address is not specified as a parameter to TransferFrom. I understand why, but to take the rationale for separating TransferFrom from Transfer further, adding the from explicitly would further reduce the risk of errors. Without this, one possible error would be to transfer a token that the operator owns themselves, while intending to transfer only a token owned by another party.

Adding the from address would require either limiting the batching scope to a single owner (by specifying a single from address in the call) or a more complicated parameter structure that can batch over multiple owners while specifying each.

fn TransferFrom({to: Address, tokens: {from: Address, tokens: TokenID[]}[], operatorData: Bytes})

Even more interesting is the lack of from in the receiver hook payload. I think this compromises the hook utility so far that it must change. Without knowing from for each token, any kind of vault or staking actor would be unable to use the hook data to internally credit the tokens to the depositor.

A more complicated data structure could again describe a batch of tokens associated with different from addresses. But overall here I think that it would be simpler to sacrifice some of the batching possibilities to simplicity. I propose adding a single from field to the hook payload. This would mean that either we restrict TransferFrom to a single owner, or have the token invoke the hook multiple times for different froms. I reckon the latter is too complicated, and we should limit batching to per-owner-address.

[alexytsu]

The from address was omitted since as you've pointed out it adds a layer of complexity when operators attempt to transfer a batch of tokens owned across different accounts.

Without knowing from for each token, any kind of vault or staking actor would be unable to use the hook data to internally credit the tokens to the depositor.

This was an oversight in the use case of the receiver hooks, so lets change TransferFrom to specify a single owner.

Note that the account that owns a token is not considered to be an operator on that token nor are accounts reflexive operators on themselves. So by default calling TransferFrom on a token owned by operator themselves would fail. The operator could explicitly set themselves as an operator on a token they own in which case TransferFrom would work.

[anorth]

calling TransferFrom on a token owned by operator themselves would fail.

Works for me. This is another case where the caller is likely to have made an error.

[anorth]

Similar reasoning applies to BurnFrom. There's no hook here, but I think we should make owner/from explicit anyway.

[anorth]

I think the pagination API is not quite sufficient. We're not mandating that token IDs be dense, small integers. Without knowing the range of IDs, a caller can't choose good initial values for pagination. E.g. there may be zero IDs in the range (0, 1000), but the return value of an empty list doesn't carry any information about whether there are tokens with higher IDs.

I suggest that the parameters might instead be (first ID, count). The token must return count IDs if they exist. The caller can assume there might be further token IDs if the return value is of length count (but there might also be zero remaining).

[anorth]

Re approval semantics, ERC-721 approve says:

Throws unless msg.sender is the current NFT owner, or an authorized operator of the current owner.

This suggests that an address that was nominated via SetApprovalForAll can approve other addresses for specific tokens. But it can't call SetApprovalForAll, and neither can an address approved for a single token approve some other address for that token.

So, should we follow the prior art in this case of allowing an account-wide authorised operator to delegate operation of specific tokens?

[alexytsu]

SGTM

[Stebalien]

I'm not sure what the right solution is right now, but having Symbol() is kind of useless given that there's no guarantee of uniqueness. Ideally we'd have a registry system of some form.

Would explorers not have an explicit list of known NFT actor types to symbols? I assume that's the only secure way to do it (again, without a registry).

[anorth]

I don't think a uniqueness guarantee is desirable. That would only lead to scarcity, a rush, speculation on names etc.

Symbol is less relevant to NFT than fungible tokens, but retained for alignment with that standard, and common practise in the ecosystem. It's basically just "short name" .

[Stebalien]

I guess... My concern is that people may implicitly trust it (e.g., use it in UIs) and get scammed.

[anorth]

Yeah I hear you. This is part of a big centralisation vs trustworthiness tradeoff. We could centralise more, but then you have to add trusted parties, or mechanisms to establish social trust, or get speculation on the value of that trust etc. At what level should that happen? I generally think the basic token API is too low a level to bring in something like that (tho Solana offers an interesting alternative point on the spectrum). Trusted registry things could be built higher up, but there doesn't seem to have been great demand for them to date.

[Stebalien]

Generally, tickers are relative to some "exchange". However, I guess that means having a ticker symbol here is fine. If/when an NFT is registered with an exchange, the exchange would:

1. Check for uniqueness.
2. Likely check to make sure that the symbol isn't being used on some other well-known exchange.

But that's not really an issue for this FIP.

[Stebalien]

Enumerable TokenIDs

Counts and bitfields are tricky. There will likely be counts for which the bitfield may be too large to return in one go, but that depends on the bitfield and how packed it is.

I would consider instead defining this method as:

fn ListTokens(rangeStart: TokenID) -> {tokens: TokenList, more: bool}

That way, the actor can decide how many to return based on how sparse the bitfield is. For example, it might want to return some number of ranges of token IDs rather than a specific number of token IDs.

[anorth]

This is a very good point. @alexytsu I think we should take @Stebalien 's suggestion here. We could still add/retain a "max" parameter which sets an upper bound on the number to return, but not require it to also be the lower bound.

[alexytsu]

I agree with the problem outlined here and having the token-actor decide what range to return.

I propose a small modification for the return value

fn ListTokens(rangeStart: TokenID) -> {tokens: TokenList, rangeEnd: TokenID}

the returned list must be all the tokens within rangeStart - rangeEnd inclusive

[Stebalien]

RangeEnd seems redundant, no? I can already get that from the token list.

[alexytsu]

If the token actor is iterating over fixed ranges (or in other iteration strategies), the last token ID returned is not necessarily the end of the checked range.

We could instead mandate that the last token ID must be the end of the checked range in order to retain a more compressed return value.

[anorth]

If rangeEnd is phrased instead as next (and is one past the end) then that's more obvious, and a fairly common pattern

[anorth]

One divergence from the fungible token is that this currently uses u64 for balances (including total supply). I feel a bit uneasy about this. On the one hand, it's a pretty big number, and it goes with u64 for token IDs. But on the other hand, I'm nervous this will limit some applications in the future of vastly abundant, almost fungible tokens.

An alternative is BigInt or []byte for token IDs, then TokenAmount for balances. This would remove any limits, while raising a bit of a question about RLE+ encoding for efficient batch representation.