Skip to content

Home

Jump to bottom
Robert La Ferla edited this page Jan 6, 2023 · 8 revisions

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 Signer 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 Signer app)

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

CLI Command Definitions

USAGE:
    metadata-cli [OPTIONS] <SUBCOMMAND>

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

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

% 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 metadata into QR code

% metadata-cli check-deployment

  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

  1. Fetches all spec and metadata QR codes
  2. Iterates through each chain in config.toml
    • Fetches the chain specs and metadata
    • Gets active metadata version
    • Checks if there is an existing metadata QR image file
    • Checks if there is an existing chainspec QR image file
    • Determines if a metadata QR file is of a later version than the metadata currently deployed
    • Updates a symlink to point to the latest metadata QR imagefile
    • Builds a map containing the chain name to a list of spec values
  3. Writes the map to public/data.json

% metadata-cli sign

  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 Signer 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 Signer 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
Clone this wiki locally