Metadata for Verification
  • 16 Jul 2024
  • 7 Minutes to read
  • Dark
    Light
  • PDF

Metadata for Verification

  • Dark
    Light
  • PDF

Article summary

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

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.

  • 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.

account_locker

Address

Primary Account Locker for the dApp

Registers the given account locker as the primary account locker for the dApp. The account locker should also be two-way linked to the dApp, using claimed_entities entry on the dApp definition, and dapp_definition entry on the account locker.

A correctly two-way-linked account_locker can be used by wallets to check for outstanding claims from dApps the user has previously interacted with. This feature is planned for the official Radix wallet, but not currently implemented as of July 2024.

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.

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


Was this article helpful?