Metadata for Verification

Introduction

An important aspect of Radix metadata standards is the concept of the dApp Definition system. This a specific set of metadata fields set with the purpose of verifying the identity and relationships between a dApp and other entities like resources, components, and packages.

It all starts with creating an on-ledger entity called a dApp Definition. Creating a dApp Definition for your dApp will provide the necessary information for clients like the Radix Wallet to let users interact with your dApp in a way that is easy, safe, and informative.

A dApp Definition is an account that is a repository of metadata that describes the dApp and things that are related to it (and may also serve as a repository for badges the creator of the dApp wishes to hold there). The dApp Definition account address acts as the unique on-ledger identifier for the dApp.

Whether you are just creating a website that interacts with the Radix Wallet, strictly creating a set of on-ledger Radix components, or creating a complex dApp including on- and off-ledger parts, you need to create a dApp Definition to identify it to the Radix Wallet.

That dApp Definition should contain metadata for wallet display use. But also, this document describes other metadata fields set on the dApp Definition and the websites, resources, components, and blueprints associated with your dApp to allow the Radix Wallet to verify for its users what truly belongs to your dApp.

Summary of Usage

An account declares itself to be a dApp Definition by setting the metadata field account_type to dapp definition. Other informational metadata fields should be set according to Metadata Standards for Wallet Display.

To create a verifiable association between that dApp Definition and other parts of your dApp, we need a 2-way link. The dApp Definition must claim those other things via metadata, and each thing must in turn confirm that claim by settings its own metadata pointing back to the dApp Definition. Once the 2-way linking of metadata is in place, the Radix Wallet can trust that association and present it to the user.

This creates a “hub and spoke” model, where the dApp Definition is the hub of your dApp.

An example of a full dApp and the metadata set on each part of it might look as follows:

dapp definition linking

With those 2-way links, the Radix Wallet (or other client software) can confidently recognize and show the related things a part of a particular dApp, and use the address as a unique identifier for the dApp.

In fact, more complex structures are possible. Resources may confirm claims by multiple dApp Definitions (for example if a token was recognized by two different dApps). And dApp Definitions themselves may also use a dapp_definitions metadata field to both claim and confirm peer relationships between multiple dApps.

A more complex dApp Definition system might look like this:

dapp definition linking complex

Declaration and handling of claimed_websites

Not only on-ledger entities can be associated with a dApp Definition. Associating a dApp’s website(s) with its on-ledger dApp Definition is crucial to verify the origin of requests to the Radix Wallet.

It is in fact required by the Radix Wallet that a dApp Website have a correctly configured dApp Definition.

Linking a dApp Definition to Websites

To declare a website (or websites) as part of a dApp, the dApp Definition sets a claimed_websites metadata field.

If more than one website is specified, the first website listed should be the primary landing page that is your preferred entry point for users. A client like the Radix Wallet might link to this first website if the full listing of websites is not shown.

Performing the link back to the dApp Definition on-ledger things (packages, components, resources, and addresses) is easily done using the dapp_definition or dapp_definitions metadata field (depending on the type of entity), as shown in the diagram above. However, it is not so clear how to do this linking for websites, which are off-ledger.

For websites, the developer must create a radix.json file at an expected location that a client like a wallet may reliably find, and within this file declare the link back to the dApp Definition (or potentially multiple dApp Definitions).

We propose adopting the RFC 8615: Well-known URI standard. This means that the radix.json file must be put in a .well-known directory at the root of the domain. This radix.json file specifies a list of dApps hosted at that domain, each with its own (definition) Address.

For example, if a dApp Definition metadata identified the website location as https://test.topradixdevs.io/collabofi, then the wallet will look for confirmation of the link in an entry at https://test.topradixdevs.io/.well-known/radix.json.

A radix.json file for a domain hosting 2 dApps would be structured like this:

{
  "dApps": [
    {
      "dAppDefinitionAddress": "account_rdx1qluj95c7hduuvrt5jctcj059qfavznygcssrgnuk0k6q3cktjy"
    },
    {
      "dAppDefinitionAddress": "account_rdx1q7u4e5vry33qyddxpm0fhqspl5ruym7zx9kj9h0d52qsf4jc9p"
    }
  ]
}

Note, while this means that one domain can host multiple dApps, there is no enforcement of separation of these dApps – it is assumed that each domain owner is in control of all dApps hosted on that domain. Each dApp must be listed in the radix.json file at the root level of their domain to be considered valid, and it is up to each dApp to correctly declare which dApp Definition it is associated with under that domain.

Using this information on the website and on the dApp Definition, the Radix Wallet can verify that requests from websites are genuine. The Wallet will know each dApp by its dApp Definition address, and no website can falsely claim to be associated with a dApp Definition that it does not actually control.

Metadata Standards for Verification of On-ledger Entities

The following details the various fields of metadata that should be configured on your on-ledger entities that make up your dApp – including the dApp Definition “hub”, and the various resource, component, and package “spokes”.

dApp Definition Accounts

Metadata field

Type

Intended Use

Radix Wallet Treatment

account_type

string

  • “dapp definition”

  • Indicates that the metadata of this account should be read as a dapp definition, including looking for the metadata below, rather than treated as a user account.

claimed_entities

Vec<Address>

  • Addresses of related entities.

  • Claims ownership of packages, components, and resources - confirmed by the entity’s metadata pointing back to this dApp Definition address.

  • claimed_entities beyond the first 100 set on this account may be ignored.

claimed_websites

Vec<Origin>

  • Origins (URLs without any path) of associated websites.

  • Claims ownership of websites - confirmed by looking up an expected .well-known/radix.json file at the claimed website origin. This will be required for your dApp to successfully send requests to the Radix Wallet at mainnet, but this is ignored when the wallet is in Developer Mode. See the section on claimed_websites for more information on setting this up correctly.

  • Note the difference between an Origin and a URL. Using a "URL" here would not be valid and be ignored.

  • claimed_websites beyond the first 10 set on this account may be ignored.

dapp_definitions

Vec<Address>

  • dApp definition account addresses.

  • Claims association with another dApp Definition - confirmed by that dApp Definition pointing back to this one in the same way. This is more of a “peer” association than it is “ownership”.

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

Resources

Metadata field

Type

Intended Use

Radix Wallet Treatment

dapp_definitions

Vec<Address>

  • dApp definition account address(es) that have claimed this as a related resource, to confirm the claim.

  • Allows display of which dApp(s) this token is associated with, if the association is confirmed by including this resource’s address in the dApp definition account’s claimed_entities metadata.

  • See “Account (for dApp definitions)” in this document for more information about cross-linking.

  • dapp_definitions beyond the first 5 set on this resource may be ignored.

Components and Blueprint Packages

Metadata field

Type

Intended Use

Radix Wallet Treatment

dapp_definition

Address

  • dApp definition account address.

  • This is important for user transparency when they sign transaction interacting with blueprints - which may happen in the case of, for example, a “factory pattern” blueprint that instantiates many components according to user needs. Allows display of which dApp this blueprint is associated with, if the association is confirmed by including this blueprint’s address in the dApp definition account’s claimed_entities metadata.

    • See “Account (for dApp definitions)” in this document for more information about cross-linking.

  • Note: This association can only be confirmed if this is cross-linked with the dApp Definition Account’s claimed_entities metadata.