oasisprotocol/metadata-registry

Registry of signed statements

Oasis Metadata Registry

This repository contains an off-chain registry of signed statements about various entities that may exist on the Oasis Network. Each statement is self-certifying and should be independently verified before being used.

For tooling that can be used to verify and access the signed statements programatically see the metadata-registry-tools repository.

Contributing New Statements

New statements can be contributed by opening a pull request.

To create an entity metadata statement using metadata-registry-tools, use the following steps:

1. Create an entity-metadata.json file describing the metadata statement, for example something like (most fields can be omitted):

   {
     "v": 1,
     "serial": 1,
     "name": "My entity name",
     "url": "https://my.entity/url",
     "email": "[email protected]",
     "keybase": "keybase_handle",
     "twitter": "twitter_handle"
   }

   Note that keybase and twitter fields should contain handles (usernames) not URLs. See ADR 0001 for the description of all the field formats.

   In case you are updating an existing entry, you must bump the serial number.

2. Fork this repository.

3. Use the oasis-cli (minimum version 0.7.1) command to generate a new signed statement. For example:

   oasis account entity metadata-update \
      --account my-entity-account \
      --registry-dir /path/to/metadata-registry \
      /path/to/entity-metadata.json

   Note that for --registry-dir you must specify the path to the top-level metadata-registry directory (e.g. the one containing this README file) and not any of its subdirectories.

   This will create (or update) the registry entry.

4. Commit your changes in the registry/ directory and create a pull request. Make sure to NOT commit the plain entity-metadata.json file in case you created it in the same directory. The same metadata can be extracted from the generated signed entity statement.

5. Automated checks will make sure that the signed statement is valid and that the update has been performed correctly.

6. If all checks pass your pull request will be approved and merged. Once this happens the updated entity metadata will be available for queries.

Directories

• docs: Documentation and specifications for the registry.
• registry: Actual registry of signed statements.

metadata-registry's Issues

Add verification actions

Once oasisprotocol/metadata-registry-tools#1 is merged, we should use that tooling to automatically verify the integrity of the registry (on the production branch and all PRs against that branch). Additionally, when submitting PRs, CI should check that existing statements cannot be removed (only updated or added) and that serial numbers have been correctly bumped.

Add logo field

For some explorer and tools that need to direct display validator information, displaying logo is a very necessary function. Hope add logo field.

Ambiguous keybase/twitter fields

For entity-metadata.json file, I have seen some people submit different keybase and twitter fields. hope it is clear whether this is an address or a handle

{
  "v": 1,
  "serial": 1,
  "name": "My entity name",
  "url": "https://my.entity/url",
  "email": "[email protected]",
  "keybase": "myentity",  #https://twitter.com/BitCat365 or BitCat365
  "twitter": "myentity"  #https://keybase.io/bitcat365 or FAB46CEEAEAB9FA1
}

Reverse statement proofs

We should specify a way to make reverse statement proofs of the linked accounts, for example:

• For URLs, a signed reverse statement to be published in HTML metadata or at a well-known path.
• For Twitter handles a signed reverse statement to be published as a Twitter post.
• For Keybase handles a signed reverse statement to be published in the Keybase filesystem.

The registry tooling would could then optionally check these reverse statements and reject invalid statements. The metadata registry could enable these checks and thus only accept verified statements (removing any which fail periodic re-verification).