Home

Frequency Metadata Portal

Overview

The Frequency Metadata Portal is a website that shows users the latest metadata for the Frequency blockchain for use with the Parity Vault mobile app. It utilizes static and video QR bar codes.

The URL for accessing the portal is:

https://metadata.frequency.xyz

The portal is intended for use by:

• Frequency developers (to validate and sign metadata)
• Council members, Sudo key holders and Frequency users (to sign transactions with the Parity Vault app)

Parity Vault mobile app (air-gapped wallet) https://signer.parity.io

CLI Command Definitions

Usage: metadata-cli [OPTIONS] <COMMAND>

Commands:
  clean             Remove unused QR codes
  collect           Generate json data file for frontend
  sign              Sign unsigned QR codes
  auto-sign         Update and autosign QR codes
  update            Check updates
  verify            Verify signed QR codes
  check-deployment  Check if deployment is up to date
  help              Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>  Path to config file [default: config.toml]
  -h, --help             Print help

% metadata-cli auto-sign

1. This subcommand can update and automatically sign the QR bar codes from either a live node or from the GitHub release assets. By default, it updates from a node.
   • To update from a node: metadata-cli auto-sign -s node
   • To update from GitHub: metadata-cli auto-sign -s github
2. Iterates through each chain in config.toml
   • Fetches chain specs and metadata for each chain
   • Generates a signed QR code for each chain spec
   • If the metadata version is not equal to the current version
     1. Generates a new video QR code
     2. Inserts source info (type and block hash) into QR code

% metadata-cli check-deployment

This compares the a freshly generated data.json against the same file fetched from the live portal to see if it is up-to-date or needs to be redeployed.

1. Generates the contents of a data.json and compares the generated file with the hosted data.json stored at the root of the homepage specified in package.json; for example: https://metadata.frequency.xyz/data.json
2. If generated vs hosted data.json mismatch, exit(12)

% metadata-cli clean

1. Obtains a list of:
   • All QR image files in public/qr
   • Each metadata QR image file
   • Each chainspec QR image file
2. Fetches the chain specs
3. Instantiates a HashSet to store files to keep
4. Iterates through each chain in config.toml
   • Determines the current metadata version from the chain specs
   • Determines which metadata QR files are versioned equal to or greater than the current metadata version; these files are kept in the HashSet
   • Stores chainspec QR files are kept in the HashSet
5. Determines the difference of all files and kept files, these are the files to be removed
6. Iterates through each file to be removed and delete it

% metadata-cli collect

Exports specifications and metadata for multiple chains defined in config.toml to the data.json file used by the web UI

1. Retrieves the specifications and metadata for each chain
2. Collects associated QR code images from the public/qr folder.
3. Constructs an ExportChainSpec object for each chain.
4. Serializes each object in the file, public/data.json

% metadata-cli sign (manual signing only)

1. Obtains a list of unsigned QR image files in public/qr
2. Iterates through the list of unsigned QR image files
   • Prompts user to select an unsigned QR image file to sign
   • Displays preview of the selected file to scan with Parity Vault mobile app
     • On macOS, the Preview app can display the .png QR image file but not the .apng QR video file for the metadata. The .apng can be opened with a browser (e.g. Google Chrome)
   • Opens the computer's camera to scan the signed chain spec or metadata produced by Parity Vault mobile app
   • Deposits the signed chain spec or metadata as a QR image file in public/qr

% metadata-cli update

1. This subcommand can update (for later manual signing) from either a live node or from the GitHub release assets. By default, it updates from a node.
   • To update from a node: metadata-cli update -s node
   • To update from GitHub: metadata-cli update -s github
2. Iterates through each chain in config.toml
   • Fetches chain specs and metadata for each chain
   • Generates a QR code for each chain spec
   • If the metadata version is not equal to the current version
     1. Generates a new video QR code
     2. Inserts metadata into QR code

% metadata-cli verify

1. Obtains a list of all QR barcode image files in public/qr
2. Iterates through the files
   • Returns an error and exit if the QR image file is unsigned
3. Iterates through the list of all QR image files (second round)
   • Determines if the QR image file is of content type metadata
     1. Determines if the signature of the metadata QR image file was produced by the private key holder of the public key provided in config.toml
     2. Returns an error and exits if the signature doesn't match

Github Actions Workflows

Auto Sign Workflow

.github/workflows/auto-sign.yml

Runs daily at 00:00:00 UTC.

auto-sign job

This job uses a branch of the format: auto-signed-<year>-<month>-<day>. The branch places signed metadata QR barcode image files into the its public/qr directory.

1. Determines if there is an updated runtime metadata from:
   • The RPC node (current version)
   • GitHub latest WASM release assets (next version)
2. If metadata has been updated:
   • Commits signed QR barcode image files to the branch
   • Creates a draft pull request
3. A maintainer of the Frequency Metadata Portal must then review the branch and merge it
   • Upon merging, the Deploy Main workflow should kick off, resulting in an update push to the Frequency Metadata Portal
   • NOTE The auto-signed-<year>-<month>-<day> branch must be deleted on merge. If a dangling auto-sign branch exists, it will be checked out by the Auto Sign workflow and may cause confusion as auto-signing will not run against main.

check-deployment job

The purpose of check-deployment is to keep the data.json up to date

1. Compares GitHub pages hosted https://metadata.frequency.xyz/data.json vs RPC fetched specs from the node
2. If the hosted vs fetched specs differ
   • Runs the collector to build a new data.json
   • Initiates the deploy workflow (.github/workflows/deploy/action.yml) to redeploy the GitHub pages hosted site with the updated data.json

Deploy Main Workflow

.github/workflows/deploy.yml

Triggered by changes to *.yml files or the config.toml in the main branch.

deploy job

The purpose of deploy is to:

1. Run the verifier to make sure all QR image files are signed by Frequency
2. Run the collector to build a new data.json
3. Redeploy the GitHub pages site with the updated data.json (by use of the deploy action)

CLI Workflow

.github/workflows/cli-test.yml

Runs on pull requests targeting the main branch with file changes in cli/**.

test job

The purpose of test is to make sure that formatting, linting and tests pass.

1. Runs cargo fmt --all -- --check
   • This currently fails on the stable channel of the Rust toolkit
2. Runs cargo clippy
3. Runs cargo test
4. Runs cargo check

Frontend Test Workflow

.github/workflows/frontend-test.yml

Runs on pull requests targeting the main branch.

frontend-test job

The purpose of frontend-test is to run linting and React tests

Verify Workflow

.github/workflows/verify.yml

Runs on pull requests targeting the main branch with file changes in public/qr/** or config.toml.

verify job

The purpose of verify is to ensure that all QR image files are signed by Frequency

Verify Skip Workflow

.github/workflows/verify-skip.yml

Runs on pull requests targeting the main branch with file changes excluding public/qr/** or config.toml.

verify-skip job

The purpose of verify-skip is to serve as a negation of the verify workflow and job

• Displays "No verification required" to signify that the file changes did NOT require re-verification