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:

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:

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 (which should have a value of Vec<Origin>).

If more than one website is specified, the first website listed should be the primary 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).

Verification follows 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 origin https://test.topradixdevs.io it would look for confirmation of the link in an entry at https://test.topradixdevs.io/.well-known/radix.json

Origin metadata values

Note that origin metadata values do not end with /. A / at the end of a url would cause an invalid origin error.

Origins and www

A dApp Definition is connected to one or more “claimed_websites”. From these, the origin is extracted, and used for the below two-way verification. This follows the web security model of the same-origin policy, where security-related data is sandboxed by origin.

Note in particular that https://www.my-cool-radix-dapp.com is a separate origin to https://my-cool-radix-dapp.com - if you wish to support users using both, you need to either:

• (a) Register both as claimed websites on your dApp Definition. The first in the list in the link will be the preferred link which is displayed to users.

• (b) Choose a canonical origin (e.g. with the www.), and set up a redirect from the other origin. Only the canonical origin needs to then be registered.

Typically (b) is a better choice as it fits better with the same-origin policy for other web security concerns, but (a) is also possible.

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.

Gumball Club Example

• dApp URL is: https://gumball-club.radixdlt.com/ which gives an origin of https://gumball-club.radixdlt.com

• Well Known radix.json file: https://gumball-club.radixdlt.com/.well-known/radix.json

• Dashboard Examples: Current dApp Definition metadata | Transaction which set up the claimed_websites

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

Resources

Components and Blueprint Packages