[SEP-50] Non-Fungible Tokens

[ozgunozerk]

Preamble

SEP: TBD
Title: Non-Fungible Tokens SEP
Author: OpenZeppelin, Boyan Barakov <@brozorec>, Özgün Özerk <@ozgunozerk>
Track: Standard
Status: Draft
Created: 2025-03-10
Updated: 2025-03-10
Version: 0.1.0
Discussion: https://github.com/stellar/stellar-protocol/discussions/1674

Summary

This proposal defines a standard contract interface for non-fungible tokens. The interface is a similar to ERC721, but factors in the differences between Ethereum and Stellar.

Motivation

A non-fungible asset (NFT) is a fundamental concept on blockchains, representing unique and indivisible digital assets. While most blockchain ecosystems have established standards for NFTs, such as ERC-721 and ERC-1155 in Ethereum, the Stellar ecosystem lacks a standardized interface for NFTs. This absence may lead to fragmentation, making it difficult to ensure interoperability between different NFT contracts and applications.

Currently, while it is technically possible to create NFTs on Stellar by issuing non-divisible assets with unique metadata as outlined in SEP-39 -and one can deploy the SAC for it afterwards-, this approach is unintuitive for developers, due to SAC is mainly designed for Fungible tokens, and comes with the following limitations:

• Non Fungibility - There are two alternatives to issue NFTs via Classic Stellar Assets: one Asset per NFT, or one Asset per collection. One Asset per NFT requires the creation of a new Classic Stellar Asset for each NFT, which can be cumbersome and inefficient. One Asset per collection resolves this problem, but then the NFTs inside the collection are becoming fungible instead of non-fungible (one can exchange an NFT inside the collection for another NFT inside the same collection).
• Metadata handling – SAC NFTs store metadata off-chain, whereas if wanted, smart contract NFTs can store more on-chain metadata with further customizations.
• Permission controls – SACs follow the standard asset authorization model, while smart contract NFTs enable fine-grained access controls and custom rules.
• Transfers & ownership – SAC NFTs rely on trust-lines and asset balances, whereas smart contract NFTs can implement more explicit and flexible ownership structures.
• Customizability – SACs are limited to predefined asset behaviors, whereas smart contract NFTs allow advanced logic like royalties, leasing, or dynamic attributes.

By defining NFTs as smart contracts, developers gain more intuitive and straight-forward way to issue NFTs, along with greater flexibility, programmability, and interoperability, enabling use cases beyond simple asset issuance.

This proposal defines a non-fungible token interface that provides core NFT functionality, including ownership management, transfers, and approvals, without enforcing opinionated behaviors beyond the standard expectations for NFTs. By establishing this interface, NFT contracts can interact seamlessly with other contracts and applications that support the standard, ensuring broader usability and compatibility within the Stellar network.

Interface

NFTs can have diverse use cases, and there is no universal token_id format that fits all scenarios. Some implementations may use sequential numbers, while others may opt for UUIDs or hashes. To accommodate this variability, this interface remains agnostic to the specific token_id format, defining it as a generic TokenID type, which should be an unsigned integer.

Additionally, since a single account cannot hold more tokens than the total supply of TokenIDs, we introduce a Balance type. In most cases, Balance should use the same type as TokenID for consistency.

/// The `NonFungibleToken` trait defines the core functionality for non-fungible
/// tokens. It provides a standard interface for managing
/// transfers and approvals associated with non-fungible tokens.
pub trait NonFungibleToken {
    /// Returns the number of tokens in `owner`'s account.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `owner` - Account of the token's owner.
    fn balance(e: &Env, owner: Address) -> Balance;

    /// Returns the address of the owner of the given `token_id`.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `token_id` - Token id as a number.
    ///
    /// # Notes
    ///
    /// If the token does not exist, this function is expected to panic.
    fn owner_of(e: &Env, token_id: TokenID) -> Address;

    /// Transfers `token_id` token from `from` to `to`.
    ///
    /// WARNING: Note that the caller is responsible to confirm that the
    /// recipient is capable of receiving the `Non-Fungible` or else the NFT
    /// may be permanently lost.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `from` - Account of the sender.
    /// * `to` - Account of the recipient.
    /// * `token_id` - Token id as a number.
    ///
    /// # Events
    ///
    /// * topics - `["transfer", from: Address, to: Address]`
    /// * data - `[token_id: TokenID]`
    fn transfer(e: &Env, from: Address, to: Address, token_id: TokenID);

    /// Transfers `token_id` token from `from` to `to` by using `spender`s
    /// approval.
    ///
    /// Unlike `transfer()`, which is used when the token owner initiates the transfer,
    /// `transfer_from()` allows an approved third party (`spender`) to transfer the token
    /// on behalf of the owner. This function includes an on-chain check to verify that
    /// `spender` has the necessary approval.
    ///
    /// WARNING: Note that the caller is responsible to confirm that the
    /// recipient is capable of receiving the `Non-Fungible` or else the NFT
    /// may be permanently lost.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `spender` - The address authorizing the transfer.
    /// * `from` - Account of the sender.
    /// * `to` - Account of the recipient.
    /// * `token_id` - Token id as a number.
    ///
    /// # Events
    ///
    /// * topics - `["transfer", from: Address, to: Address]`
    /// * data - `[token_id: TokenID]`
    fn transfer_from(e: &Env, spender: Address, from: Address, to: Address, token_id: TokenID);

    /// Gives permission to `approved` to transfer `token_id` token to another
    /// account. The approval is cleared when the token is transferred.
    ///
    /// Only a single account can be approved at a time for a `token_id`.
    /// To remove an approval, the approver can approve their own address,
    /// effectively removing the previous approved address.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to Soroban environment.
    /// * `approver` - The address of the approver (should be `owner` or `operator`).
    /// * `approved` - The address receiving the approval.
    /// * `token_id` - Token id as a number.
    /// * `live_until_ledger` - The ledger number at which the allowance
    ///   expires.
    ///
    /// # Events
    ///
    /// * topics - `["approve", from: Address, to: Address]`
    /// * data - `[token_id: TokenID, live_until_ledger: u32]`
    fn approve(e: &Env, approver: Address, approved: Address, token_id: TokenID, live_until_ledger: u32);

    /// Approve or remove `operator` as an operator for the owner.
    ///
    /// Operators can call `transfer_from()` for any token held by `owner`,
    /// and call `approve()` on behalf of `owner`.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to Soroban environment.
    /// * `owner` - The address holding the tokens.
    /// * `operator` - Account to add to the set of authorized operators.
    /// * `live_until_ledger` - The ledger number at which the allowance
    ///   expires. If `live_until_ledger` is `0`, the approval is revoked.
    ///
    /// # Events
    ///
    /// * topics - `["approve_for_all", from: Address]`
    /// * data - `[operator: Address, live_until_ledger: u32]`
    fn approve_for_all(
        e: &Env,
        owner: Address,
        operator: Address,
        live_until_ledger: u32,
    );

    /// Returns the account approved for `token_id` token.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `token_id` - Token id as a number.
    ///
    /// # Notes
    ///
    /// If the token does not exist, this function is expected to panic.
    fn get_approved(e: &Env, token_id: TokenID) -> Option<Address>;

    /// Returns whether the `operator` is allowed to manage all the assets of
    /// `owner`.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `owner` - Account of the token's owner.
    /// * `operator` - Account to be checked.
    fn is_approved_for_all(e: &Env, owner: Address, operator: Address) -> bool;

    /// Returns the token collection name.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    fn name(e: &Env) -> String;

    /// Returns the token collection symbol.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    fn symbol(e: &Env) -> String;

    /// Returns the Uniform Resource Identifier (URI) for `token_id` token.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `token_id` - Token id as a number.
    ///
    /// # Notes
    ///
    /// If the token does not exist, this function is expected to panic.
    fn token_uri(e: &Env, token_id: TokenID) -> String;
}

Events

Transfer Event

The transfer event is emitted when an NFT is transferred from one address to another.

Topics:

• Symbol with value "transfer"
• Address: the address holding the token that was transferred.
• Address: the address that received the token.

Data:

• TokenID: the identifier of the transferred token.

Approve Event

The "approve" event is emitted when an owner grants another address permission to manage a specific token.

Topics:

• Symbol with value "approve"
• Address: the owner of the token.
• TokenID: the identifier of the token.

Data:

• Address: the approved address.
• u32: the expiration ledger.

Approve for All Event

The "approve for all event" is emitted when an owner grants or revokes permission for an operator to manage all of their NFTs.

Topics:

• Symbol with value "approve_for_all"
• Address: the owner of the tokens.

Data:

• Address: the operator receiving or losing permission.
• u32: the expiration ledger. If 0, the approval is revoked.

Mint Event

The mint event is emitted when a token is minted.

The event has topics:

• Symbol with value "mint"
• Address: the address to hold the newly minted token.

The event has data:

• TokenID the identifier of the minted token.

Notes on mint():

• Minting functionality is typically implemented as an internal function (see [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts)) to emphasize that the standard does not impose any specific minting logic. This allows developers to adopt an approach that best suits their contract’s requirements. In this SEP, we do not specify any standards for minting tokens.

Notes on safeTransferFrom:

• In ERC-721, safeTransferFrom and onERC721Received exist to prevent the loss of NFTs when transferring them to a smart contract that does not support NFT-related operations.
• However, this approach comes with significant overhead:
  • An additional on-chain transaction is required for verification.
  • The receiving contract must implement onERC721Received.
• A more efficient alternative is the [permit](https://eips.ethereum.org/EIPS/eip-2612) mechanism (EIP-2612), which leverages off-chain signatures to authorize the recipient to claim the tokens, reducing on-chain transactions from two to one.

Notes on permit:

safeTransfer and onReceive ensure the recipient can handle NFTs, preventing accidental burns. Unlike fungible tokens, NFTs can’t be broken into tiny fractions, and test-transferred in small amounts.

Stellar’s trust lines offer similar safety but apply to specific assets, whereas safe transfer secures entire asset classes. Soroban removed trust line requirements for contract transfers.

safeTransferFrom is relevant for NFT transfers to smart contracts, while permit also works for EOAs, addressing the indivisibility issue. Stellar’s built-in signatures provide permit-like functionality at the protocol level. For added safety, developers can implement safe variants or leverage existing solutions.

Notes on transfer():

• The transfer() function exists in ERC20 but is absent in ERC721, primarily for historical reasons. In both ERC20 and ERC721, transferFrom() can be used instead of transfer(), with the the only difference being an additional on-chain check. To avoid redundancy, transfer() was omitted from the ERC721 standard.
• Despite this, transfer() retains a key advantage over transferFrom(): when the token owner initiates the transfer, transfer() is more efficient and cost-effective, as it eliminates the need for an extra on-chain verification.
• While we aim for compatibility with other ecosystems, maintaining internal consistency within our own ecosystem takes precedence. The behavior and the use cases of transfer() remains the same for both fungible and non-fungible tokens, so we decided to include it for NFTs as well in this SEP.

Notes on name(), symbol() and token_uri()

• Those methods are not part of ERC721, but including them in the standard, because exposing metadata through this API proved itself as a common practice for marketplaces to display NFT details. Furthermore, it’s important to be consistent within the Stellar ecosystem as SEP-41 also defines metadata as part of the core interface for fungible tokens.
• [SEP-39](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0039.md#design-rationale) suggests a dual approach for describing NFTs. The first one proposes an example json schema, while the other suggests leveraging the defined in SEP-1 “Stellar.toml”. While this approach makes sense for NFTs represented by Classic Stellar Assets, it can create confusion for clients. To prevent this, token_uri() returns an url that points to a JSON file that conforms to the "Non-Fungible Metadata JSON Schema".
• "Non-Fungible Metadata JSON Schema"

{
  "title": "Non-Fungible Metadata",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Identifies the asset to which this NFT represents"
    },
    "description": {
      "type": "string",
      "description": "Describes the asset to which this NFT represents"
    },
    "image": {
      "type": "string",
      "description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents."
    },
    "external_url": {
      "type": "string",
      "description": "A URL pointing to an external resource related to the asset, for example, to visualize the NFT on the collection's own site."
    },
    "attributes": {
      "type": "array",
      "description": "Array of attributes that describe the asset",
      "items": {
        "type": "object",
        "properties": {
          "display_type": {
            "type": "string",
            "description": "The type of display for the attribute"
          },
          "trait_type": {
            "type": "string",
            "description": "The type of trait this attribute represents"
          },
          "value": {
            "description": "The value of the attribute",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "max_value": {
            "type": "number",
            "description": "The maximum value for numeric traits"
          }
        }
      }
    }
  }
}

[anataliocs]

In terms of metadata, are the Opensea standards considered canonical

https://docs.opensea.io/docs/metadata-standards

[janewang]

Should attributes be an array "attributes": [...]? Its type is defined as array, but from the JSON, it looks like an object.

[ElliotFriend]

That's just the way JSON schema works, I think. It's thrown me off before too, but this object is the way they're describing how the attributes array should look.

[brozorec]

In terms of metadata, are the Opensea standards considered canonical

They turned to be the de-facto standard. We could have been more permissive about the structure of attributes. Does this schema impose too many limitations?

[ElliotFriend]

The approve, set_approval_for_all, and is_approved_for_all functions take an allowed address as either approved or operator. I might suggest we aim to mirror the SEP-41 word of spender here for all of them. It seems a little inconsistent that approve calls the approved address approved, while set_approval_for_all calls a boolean flag approved. I think spender is a little clearer about what that argument/address is authorized to do. (Unless there is pre-existing technical or semantic meaning to operator/approved that I'm unaware of).

I had some more general thoughts on the approve and set_approval_for_all function, too. Here's an NFT contract I'm currently working on, for reference. If we allow the expiration_ledger to serve double-duty, we don't really need the boolean flag in approve for all. In my thinking, expiration ledger can be passed as 0 to indicate that the approval should be rescinded. Essentially force-expiring it. That could allow us to re-use the same struct to store both approve and approve for all storage entries. Then, the footprint of both functions is much more similar to one another, as well. I'm happy to learn if/why those are bad strategies/techniques. But, from my use it seems like it results in a more consistent set of function arguments.

(Completely inconsequential thought: set_approval_for_all feels like a mouthful lol. Are we married to that, since it's the ERC721 language? Personally, approve_all feels like a nice and concise function name. And, it feels more "similar" to approve.)

This might wade into "implementation" territory, but would we want to make recommendations for a minting event? Or, is that usually handled like any other transfer event? I'm totally fine either way, just wanted to throw the question out there.

[ozgunozerk]

The approve, set_approval_for_all, and is_approved_for_all functions take an allowed address as either approved or operator. I might suggest we aim to mirror the SEP-41 word of spender here for all of them.

We are using the word spender in transfer*() functions, however, operator and approver are different things. For example, operator can grant approval on behalf of the owner to other accounts (in other words, has the privilege to call approve() function; approved on the other hand, cannot do that). Also, operator has authority over all the tokens of the owner, whereas approved has authority over only a single token of the owner.

So, I think keeping them as is would be better to prevent confusions.

It seems a little inconsistent that approve calls the approved address approved, while set_approval_for_all calls a boolean flag approved

We also realized that and got annoyed by approved used in 2 difference contexts. We revised it as is_approved for the boolean flag 👍

If we allow the expiration_ledger to serve double-duty, we don't really need the boolean flag in approve for all. In my thinking, expiration ledger can be passed as 0 to indicate that the approval should be rescinded. Essentially force-expiring it.

That's a great suggestion imo! Will think on it a bit more just in case 👍

Completely inconsequential thought: set_approval_for_all feels like a mouthful lol. Are we married to that, since it's the ERC721 language? Personally, approve_all feels like a nice and concise function name. And, it feels more "similar" to approve.

We are trying our best to follow the consistency across different ecosystems. Yet, being consistent within the ecosystem of course take precedence. It is mouthful, I agree, but doesn't cause any inconsistencies within Stellar as well, and it would be more familiar for those who are coming from other ecosystems to keep it as is. There is no objectively good answer to this though 🤷 .

This might wade into "implementation" territory, but would we want to make recommendations for a minting event? Or, is that usually handled like any other transfer event? I'm totally fine either way, just wanted to throw the question out there.

We are planning to handle that by mintable related extensions.

[ozgunozerk]

Updated the content:

• is_approved is removed as suggested (live_until_ledger will be utilized for the revoke).
• mint event is added

Thanks for the suggestions!

[ElliotFriend]

Had a thought on the use of the u128 type for an NFT's token_id. Unless I'm mistaken, a u128 integer will store 20 bytes on-chain, whereas a u32 will store 8. I think we could save some storage space and minimize fees if we switch to u32 for token IDs. The max tokens then is limited to ~4billion, which still seems sufficient to me.

I'm not confident about how much of a tangible effect this would have, though. I think @leighmcculloch or @dmkozh might have some knowledge they could share on that (or, they are probably well-situated to tell me I'm completely off-base lol).

[ozgunozerk]

@leighmcculloch maybe I misunderstood, but I wasn't talking about generics.
I was talking about associated types. What I had in mind was:

pub trait NonFungibleToken {
    type TokenId;

    fn transfer(e: &Env, from: Address, to: Address, token_id: Self::TokenId);

would this be problematic for the current capabilities?

[ozgunozerk]

I think there is a better choice, since associated types does not resolve issues with events or free functions or structs that does not know about the associated type of the trait.

Instead, we can specify something like this:

type TokenID = /* set this to your preferred type */

pub trait NonFungibleToken {
    /* inside the trait, and everywhere else where `u32` is used for the `token_id` type, we will now use `TokenID` */
}

[leighmcculloch]

Assuming the trait has only a single implementation per crate, then the type value seems fine as a shorthand and a great way to make it easy for people to change when copy-pasting. I'd still specify that the type is Val in the SEP specification, pointing out that the implementers can narrow the type of TokenID to any type that converts to/from Val.

An associated type would be needed if the goal was to make this into a library though.

I don't think the associated type is supported today by the contractimpl macro, but I think the path for supporting that is easier than generic types. So I do think associated types is a reasonable path. The way that I'd recommend we encode the associated type into the final Spec XDR would be the flatten it everywhere as if it was just a type alias. So nothing new would need adding to the XDR. Using the associated type would help with making it a trait in a library though if that was the plan.

[ozgunozerk]

Agreed on everything about the SEP, will update this and the PR soon! Thanks for the feedback

Edit: updated 🚀

[leighmcculloch]

An example of what I was meaning about hiding the implementation detail of the ID type behind Val in the contract interface:

• Add an example contract that uses Val as an ID type soroban-examples#370

[dmkozh]

SEP-41 is going to be updated to include the mint event spec for the sake of easier integration with the event consumers (like block explorers). I think it would make sense for this SEP to contain the mint event spec from the get-go.

[ozgunozerk]

Updated the content and included the mint event, thanks for the suggestion!

[leighmcculloch]

The approve and set_approval_for_all functions are named differently. I think we could rename set_approval_for_all to approve_for_all so there's some clearer relatedness through naming. The different naming raises the question on glance if the functions are named differently, do they take significantly different action, however they take the same actions with different scope.

I think we can rename the approval event to approve for consistency with SEP-41, and approval_for_all to approve_for_all so they follow the same naming pattern. I don't think consistency with SEP-41 is required, but maybe helpful so that folks don't get similar words and terms mixed up when moving back and forth between them.

[kalepail]

I have a more philosophical question as to how we think standards like this will be implemented by wallets. Right now as I understand it all our ecosystem wallets populate asset data from a home_domain stellar.toml file. https://developers.stellar.org/docs/build/apps/example-application-tutorial/anchor-integration/sep1 Are we suggesting or thinking as we begin to move towards smart contract only or smart contract first standards that we will continue to rely on home domains and stellar.toml files or will wallet providers need to maintain two canonical methods for deriving asset information? I haven't done much thinking here but I do think it's important we consider either here or in subsequent SEP standards how we think we'll marry the existing asset metadata mechanics of the stellar.toml with new contract methods for retrieving asset information.

A really basic question is should our asset interfaces include a home_domain field?

[leighmcculloch]

I think it's reasonable for there to be multiple ways to serve NFTs, similar to the conversation on Discord that was discussing some NFTs continuing to use Stellar Assets.

or will wallet providers need to maintain two canonical methods for deriving asset information?

SEP-41 has already delivered an interface completely disconnected from home domains and stellar.toml. It's why the standard export functions like name, symbol, and decimals. I think this proposal is similar in it's goals to be unattached from any off-chain requirements.

A really basic question is should our asset interfaces include a home_domain field?

Maybe, but I don't think it should be required as part of this SEP. Similar to how SEP-41 doesn't require it. I think there's a place for a standalone home domain SEP that documents a single function fn home_domain() -> String. The SEP-NFT can document that if SEP-HOMEDOMAIN is also implemented, then certain fields at the home domain's stellar.toml become relevant for wallets that need it. SEP-41 could also leverage this by saying that if SEP-HOMEDOMAIN is also implemented then details about the asset/token issued can be found there also. (cc @JakeUrban)

Independent of the NFT proposal I'm starting a discussion about SEP-41 and Home Domains here.

[leighmcculloch]

I'm doing a final read through the SEP as part of hte merge process, and I noticed an inconsistency and want to check if it's intentional.

The get_approved and is_approved_for_all functions are named differently and operate differently.

The get_approved function can only ever return a single address, implying that there can only be one address approved to control a single token, which is also explicitly stated in the comments for the function.

The is_approved_for_all function however accepts an address, and so implys that there can be multiple operators who have approval for all of an owners tokens. Is that intended? Or is it intended that only a single operator can have approval for all?

This lack of symmetry presents some ambiguity:

• Can multiple operators be approved for all for an owner?
• If an operator is approved for all, does the operator show up as the approved address in get_approved?
• Does an operator for all prevent there being a single approver for a single token ID?

    /// Returns the account approved for `token_id` token.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `token_id` - Token id as a number.
    ///
    /// # Notes
    ///
    /// If the token does not exist, this function is expected to panic.
    fn get_approved(e: &Env, token_id: TokenID) -> Option<Address>;

    /// Returns whether the `operator` is allowed to manage all the assets of
    /// `owner`.
    ///
    /// # Arguments
    ///
    /// * `e` - Access to the Soroban environment.
    /// * `owner` - Account of the token's owner.
    /// * `operator` - Account to be checked.
    fn is_approved_for_all(e: &Env, owner: Address, operator: Address) -> bool;

[leighmcculloch]

I forgot that these two functions work identically to how ERC721 works, and I understand the value in consistency with that ERC because subtle inconsistencies introduced to functions like this could be easily missed and missimplemented. These questions don't need to block merging.

[ozgunozerk]

In short, yes.
get_approved returns a single address, and it indeed is intentional, there can be only one approved address for a token.

On the other hand, there can be multiple operators per address, so that is intentional as well. If there is ambiguity, we can document these.