Metadata for Wallet Display

Introduction

These metadata standards are intended to assist clients like the Radix Wallet, Radix Dashboard, exchanges, and more, to display useful information about the assets a user holds, and the on-ledger things a user interacts with, like dApps, components, and blueprints.

Developers can feel free to add and use whatever metadata they like, but these standards are recommended as a “least common denominator” standard for the basic attributes that the Radix Wallet and any other client would expect to be present in a standard way.

In short, if you set these things on the things you create, you can be sure of having clear and excellent presentation for users.

Resources

Metadata set on tokens and NFTs helps identify those assets and provide customized presentation to wallet users.

Note that, for NFTs, this is metadata set on the NFT resource itself (or “resource manager”) that refers to all individual non-fungibles that belong to that resource. Separate standards for setting data on individual non-fungibles is below.

Metadata field

Type

Intended Use

Radix Wallet Treatment

name

string

  • Simple name of the asset as intended to be displayed, with capitals.

  • Shown as primary readable identifier for token if symbol is not present (for nonfungible tokens), and as a more complete human-readable name of the token.

    • eg. Bitcoin

    • eg. Dallas Mavericks Tickets

  • May be truncated after 32 characters.

symbol (fungible resources only)

string

  • A short unique identifier, often used on exchanges or to label an amount of the token (eg. 2.503 BTC).

  • No more than 5 characters.

  • Alphanumeric, all caps, no whitespace.

  • Shown all-caps as most-preferred singular method of identifying fungible tokens. Symbol is ignored for non-fungible resources

    • eg. BTC.

  • The wallet will display the symbol all-caps.

  • Symbols not conforming to the intended string format may be ignored.

  • May be truncated after 5 characters.

description

string

  • Summarized description of the asset and its purpose as intended to be displayed, with capitals.

  • Not shown as a primary readable identifier for the token - but listed under the detailed information for the token.

    • eg. Open source P2P money.

    • eg. Your NFT tickets to see the Dallas Mavericks at the American Airlines Center.

  • Intended to provide a short, simple description in the context of a "get info" style screen. As with other metadata fields, no formatting is supported. Line breaks, extra whitespace, and other types of formatting tags should not be used - they may either be shown explicitly as text or ignored.

  • May be truncated after 256 characters.

tags

Vec<string>

  • List of descriptive tags for the resource.

  • Alphanumeric, no caps, dashes for spaces, no whitespace.

  • The wallet will allow the user to choose which tags are meaningful to them, and display these tags on resources and allow grouping by them.

    • eg. badge, gaming, loan-positions, PFP

  • The wallet will default to showing the badge tag (indicating an asset that is intended to be used for authorization). It will show a warning when the user is viewing a transaction that would transfer away a resource tagged badge.

  • All other tags will be for the user to opt-in to see flagged on their resources in a given account.

  • The wallet will default to showing the badge tag (indicating an asset that is intended to be used for authorization). All other tags will be for the user to opt-in to see flagged on their resources in a given account.

  • Tags not conforming to the intended string format may be ignored.

  • Dashes in tags may be replaced by spaces for friendly display for users.

  • May be truncated after 16 characters.

  • tags beyond the first 100 set on this resource may be ignored.

icon_url

URL

  • Location of image to be used to represent the token.

  • Should be designed for expected presentation as a circle

  • Shown as a primary visual identifier for the token in various places, if present. A placeholder is used if nothing set.

  • The wallet will load and scale this image for specific presentation, cropping it into a 1:1 circle.

  • Supported types: JPG, PNG, GIF

  • Images without proper filename extensions or of format other than PNG, JPG, or GIF format may be ignored.

  • Note: A later expansion of the metadata standard may include the ability to specify more - such as different images for different sizes and usage, explicit mutability and aspect ratio, and verifiable hashes. We start with a simple single URL field standard for now, which the Radix Wallet will always intend to support, and will expand the standard (and its adoption in the Radix Wallet) from developer community feedback.

info_url

URL

  • Direct link to an informational webpage.

  • If provided, the wallet will present this URL that may route users to an informational webpage about the token in the detailed page view of the token.

Non-fungibles

Individual NFT unit non-fungible data

“Non-fungible data” does not take the same form as the “metadata” described elsewhere in this document. Instead it is a data structure of the NFT resource manager that defines the fields and types of data that may be stored on individual non-fungibles of that resource.

However, clients may still parse and use non-fungible data for display in a very similar way as metadata, and so we list some standards of usage in this document.

Wherever non-fungible resource managers (which may be thought of as “collections” of NFTs for users) are shown in the wallet, the associated individual NFT units (non-fungibles) are shown grouped beneath the resource manager as the heading. Non-fungible data affects how each of these units are displayed under the heading.

Non-fungible data field

Type

Intended Use

Radix Wallet Treatment

name

string

  • Simple name of this particular non-fungible unit as intended to be displayed, with capitals.

  • Shown as an additional identifier along with the NonFungibleLocalId (which is universally used as the unique identifier for the non-fungible by the wallet).

    • eg. Mavs vs Lakers 12-25-2024

  • May be truncated after 32 characters.

description

string

  • Summarized description of this particular non-fungible unit as intended to be displayed, with capitals.

  • Not shown as an identifier for the NFT - only listed under the general detailed information for the non-fungible.

    • eg. This NFT grants access to the American Airlines center for the 12-25-2024 matchup between …​

  • Intended to provide a short, simple description in the context of a "get info" style screen. As with other metadata fields, no formatting is supported. Line breaks, extra whitespace, and other types of formatting tags should not be used - they may either be shown explicitly as text or ignored.

  • May be truncated after 256 characters.

key_image_url

URL

  • Location of image to be associated with this non-fungible unit.

  • A non-fungible may often represent or be closely associated with an image - whether a unique piece of art, a profile picture, or simply an image that gives a greater sense of the purpose of the NFT. The image at the URL specified here, if present, will be used in the wallet as the primary visual representation of the non-fungible, displayed prominently as a user browses their assets.

At preview level, images may be shown cropped. If wider than 16:9 (W:H), it will be cropped into the largest possible 16:9 rectangle. If taller than 1:1, it will be cropped into the largest possible 1:1 square.

A detail view will show it at full aspect ratio.

Supported types: JPG, PNG, GIF (including animated)

May be ignored for file sizes above 10MB

  • Note: A later expansion of the metadata standard may include the ability to specify more - such as different images for different sizes and usage, explicit mutability and aspect ratio, and verifiable hashes. We start with a simple single URL field standard for now, which the Radix Wallet will always intend to support, and will expand the standard (and its adoption in the Radix Wallet) from developer community feedback.

  • Note: Some NFT creators may wish to set additional data fields pointing to richer visual data (like multiple sizes, video, or 3D data), or include verifying data like a hash of the image in question. In the first instance of the Radix Wallet, this information would be shown among the “arbitrary data fields” below, with this key_image_url as the only field given special visual presentation. This wallet support may be expanded and improved as community standards emerge.

  • Also note that most decentralized data storage platforms offer a standard URL to individual files. This means that a non-fungible on Radix may be linked to decentralized image storage in this way using this data field.

[other arbitrary data fields]

Defined in the ResourceManager

  • May be truncated as needed.

  • A nonfungible resource manager specifies a specific set of available metadata fields for all of its nonfungible resources via the schema. In addition to the specially-handled metadata above, the wallet will show any additional fields as key / value pairs if the value are of simple types like strings, integers, and addresses. More complex data types may or may not be shown by the wallet necessarily.

    • eg.
      Section = G
      Seat number = 44
      Game date = 12-25-24

Not shown in this list is the NonFungibleLocalId even though this piece of data may be set by the NFT’s creator and will be shown prominently in the Radix Wallet. The NonFungibleLocalId is used to address a specific non-fungible, must be unique, and may be set by the NFT creator. Because the creator may set it, it is a useful way to “brand” a given non-fungible. For example, the NonFungibleLocalId might be a string set to “mavs_lakers_122524_44G”.

Components and Blueprint Packages

Unlike most of the metadata standards, the fields here are not primarily intended for use in the wallet, but rather for use by network browsing and searching interfaces such as the Radix Dashboard, or perhaps future Scrypto code browsing and discovery services. It might be used along with other non-metadata information about the component or package, such as the methods available or royalty fees charged for its usage.

Metadata field

Type

Intended Use

Radix Wallet Treatment

name

string

  • Simple name of the component as intended to be displayed, with capitals.

  • eg. AwesomeOracle Price/Weather

  • May be truncated after 32 characters.

description

string

  • Summarized description of the component and its usage as intended to be displayed, with capitals.

  • eg. Official AwesomeOracle component providing data about asset prices and weather conditions.

  • Intended to provide a short, simple description in the context of a "get info" style screen. As with other metadata fields, no formatting is supported. Line breaks, extra whitespace, and other types of formatting tags should not be used - they may either be shown explicitly as text or ignored.

  • May be truncated after 256 characters.

tags

Vec<string>

  • List of descriptive tags for the component.

  • Alphanumeric, no caps, dashes for spaces, no whitespace.

  • eg. oracle, price, weather

  • Tags not conforming to the intended string format may be ignored.

  • Dashes in tags may be replaced by spaces for friendly display for users.

  • May be truncated after 16 characters.

  • tags beyond the first 100 set on this resource may be ignored.

Special Native Components and Resources

The Radix Network includes a selection of native blueprints from which users can instantiate native components with known and trustable behavior. Some of these components also mint their own associated resources.

Below are the metadata standards a developer should consider to customize how these components and resources are presented in the Radix Wallet and other clients.

Metadata standards for verification may also be applied to these components and resources.

“Account” (for users) system component metadata

Accounts are the elemental holder of resources. The wallet interacts with them directly, or wraps them in an access controller component, which works by holding the owner badge issued by the account.

No metadata is expected to be set on simple account components for users.

“Account” (for dApp definitions) system components metadata

In addition to user accounts in the wallet, accounts may be used as repositories for metadata that define the collection of things that make up a “dApp” so that they have a single on-ledger identity that they may be registered to, and recognized by in the wallet. This registration is done by this component claiming ownership of other components, packages, resources, and more – and those entities in turn confirming that claim by setting metadata that points to this account’s address.

This is an account because this component may also need to hold resources of various types (in particular badges).

Metadata field

Type

Intended Use

Radix Wallet Treatment

name

string

  • Simple name of the dApp as intended to be displayed, with capitals.

  • e.g. CollaboFi

  • Intended to provide a short, simple description in the context of a "get info" style screen. As with other metadata fields, no formatting is supported. Line breaks, extra whitespace, and other types of formatting tags should not be used - they may either be shown explicitly as text or ignored.

  • May be truncated after 32 characters.

description

string

  • Summarized description of the dApp as intended to be displayed, with capitals.

  • eg. CollaboFi is a platform for collaborative community and creative crowdfunding.

  • May be truncated after 256 characters.

tags

Vec<string>

  • List of descriptive tags for the dApp.

  • Alphanumeric, no caps, dashes for spaces, no whitespace.

  • eg. dao, marketplace, music, art

  • May be truncated after 16 characters.

  • tags beyond the first 100 set on this resource may be ignored.

icon_url

URL

  • Location of image to be used to represent the dApp.

  • Should be designed for expected presentation as a square.

  • Shown as a primary visual identifier for the dApp in various places, if present. A placeholder is used if nothing set.

  • The wallet will load and scale this image for specific presentation, cropping it into a 1:1 square.

  • Supported types: JPG, PNG, GIF

  • Images without proper filename extensions or of format other than PNG, JPG, or GIF format may be ignored.

  • Note: A later expansion of the metadata standard may include the ability to specify more - such as different images for different sizes and usage, explicit mutability and aspect ratio, and verifiable hashes. We start with a simple single URL field standard for now, which the Radix Wallet will always intend to support, and will expand the standard (and its adoption in the Radix Wallet) from developer community feedback.

“Identity” system component metadata

This system component is specifically intended to be used as a repository for a public key that can be used for web3 login verification as part of the ROLA system. The Radix Wallet creates and associates an identity component with each Persona that a user creates there to be used for web3 logins. The Identity component holds no resources. The login mechanism is designed to be pseudo-anonymous, therefore there is little reason for general metadata to be stored here (and there is good reason to not store data there).

Identities have no standard metadata fields.

“Validator” system component metadata

A validator node-runner will instantiate a system Validator component that holds its stake and allows its owner to define various pieces of metadata that might be visible on a staking dashboard or the Radix Wallet. Other more functional aspects of Validator configuration, such as setting the validator’s fee, are set via component methods, not metadata.

Metadata field

Type

Intended Use

Radix Wallet Treatment

name

string

  • Simple name of the validator as intended to be displayed, with capitals.

  • eg. Prime Stake

  • May be truncated after 32 characters.

description

string

  • Summarized description of the validator as intended to be displayed, with capitals.

  • eg. Your top choice for reliable, community-driven Radix Network validation.

  • Intended to provide a short, simple description in the context of a "get info" style screen. As with other metadata fields, no formatting is supported. Line breaks, extra whitespace, and other types of formatting tags should not be used - they may either be shown explicitly as text or ignored.

  • May be truncated after 256 characters.

icon_url

URL

  • Location of image to be used to represent the validator (not to be confused with individual non-fungibles).

  • Should be designed for expected presentation as a square.

  • Shown as a primary visual identifier for the validator in various places, if present. A placeholder is used if nothing set.

  • The wallet will load and scale this image for specific presentation, cropping it into a 1:1 square.

  • Supported types: JPG, PNG, GIF

  • Images without proper filename extensions or of format other than PNG, JPG, or GIF format may be ignored.

  • Note: A later expansion of the metadata standard may include the ability to specify more - such as different images for different sizes and usage, explicit mutability and aspect ratio, and verifiable hashes. We start with a simple single URL field standard for now, which the Radix Wallet will always intend to support, and will expand the standard (and its adoption in the Radix Wallet) from developer community feedback.

info_url

URL

  • Direct link to an informational webpage.

  • If provided, the wallet will present this URL that may route users to an informational webpage about the token in the detailed page view of the token.

"Liquid Staking Unit" and "Stake Claim" resources for Validators

Validator components automatically mint liquid stake unit tokens and stake claim NFTs. It is not expected for the validator node-runner to set any metadata for these resources, and the Radix Wallet will show validator information taken from the validator component metadata as above.

“Pool” component metadata

A developer who wishes to use a pool will instantiate one from a native Pool blueprint, and they will have the ability to set metadata on it as they wish.

The metadata standards for pool components are the same as those for other components above.

"Pool Unit" resource metadata

Pool components automatically mint pool unit tokens. Instantiators of pool components will also be given the ability to set the metadata on this resource as they wish.

The metadata standards for these resources are the same as other resources above.