Oasis Metadata Registry Tools

This repository contains tools for working with the Oasis Metadata Registry.

Building

To build the oasis-registry tool, run:

make build

Usage

NOTE: Currently, you will need to build the oasis-registry tool yourself.

NOTE: Support for signing entity metadata statements with the Ledger-based signer is available in Oasis app 1.9.0+ releases which will soon be available via Ledger Live's Manager.

To sign an entity metadata statement, e.g.

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

save it as a JSON file, e.g. entity-metadata.json, and run:

./oasis-registry/oasis-registry entity update \
  <SIGNER-FLAGS> \
  entity-metadata.json

where <SIGNER-FLAGS> are replaced by the appropriate signer CLI flags for your signer (e.g. Ledger-based signer, File-based signer).

For more details, run:

./oasis-registry/oasis-registry entity update --help

NOTE: The same signer flags as used by the Oasis Node CLI are supported. See Oasis CLI Tools' documentation on Signer Flags for more details.

The oasis-registry entity update command will output a preview of the entity metadata statement you are about to sign:

You are about to sign the following entity metadata descriptor:
  Version: 1
  Serial:  1
  Name:    My entity name
  URL:     https://my.entity/url
  Email:   [email protected]
  Keybase: my_keybase_handle
  Twitter: my_twitter_handle

and ask you for confirmation.

It will store the signed entity metadata statement to the registry/entity/<HEX-ENCODED-ENTITY-PUBLIC-KEY>.json file, where <HEX-ENCODED-ENTITY-PUBLIC-KEY> corresponds to your hex-encoded entity's public key, e.g. 918cfe60b903e9d2c3003eaa78997f4fd95d66597f20cea8693e447b6637604c.json.

Contributing Entity Metadata Statement to Production Oasis Metadata Registry

See the Contributing New Statements guide at the Oasis Metadata Registry's web site.

Development

Examples

For some examples of using this Go library, check the examples/ directory.

To build all examples, run:

make build-examples

To run the lookup example that lists the entity metadata statements in the production Oasis Metadata Registry, run:

./examples/lookup/lookup

It should give an output similar to:

[ms7M1v8HfItCnNNJ0tfE/PsYQsmeD+XpfGF1v0zR2Xo=]
  Name:    Everstake
  URL:     https://everstake.one
  Email:   [email protected]
  Keybase: everstake
  Twitter: everstake_pool

[gb8SHLeDc69Elk7OTfqhtVgE2sqxrBCDQI84xKR+Bjg=]
  Name:    Bi23 Labs
  URL:     https://bi23.com
  Email:   [email protected]
  Keybase: sunxmldapp
  Twitter: bi23com

... output trimmed ...

Test Vectors

To generate the entity metadata test vectors, run:

make gen_vectors

Tests

To run all tests, run:

make test

This will run all Make's test targets which include Go unit tests and CLI tests.

NOTE: CLI tests with Ledger signer will be skipped unless the LEDGER_SIGNER_PATH is set and exported.

Tests with Ledger-based signer

To run CLI tests with Ledger-based signer, you need to follow these steps:

1. Download the latest Oasis Core Ledger release from https://github.com/oasisprotocol/oasis-core-ledger/releases.

2. Extract the oasis_core_ledger_<VERSION>_<OS>_amd64.tar.gz tarball.

3. Set LEDGER_SIGNER_PATH environment variable to the path of the extracted ledger-signer binary and export it, e.g.:

   export LEDGER_SIGNER_PATH="/path/to/oasis_core_ledger_1.2.0_linux_amd64/ledger-signer"

4. Connect your Ledger device and make sure the Oasis app is open.

5. Run tests with:

   make test-cli-ledger