Frequency is a Polkadot parachain for data distribution protocols such as DSNP.

• Table of Contents
• Prerequisites
  • Hardware
• Build
  • Local Desktop
    • asdf Support
  • Remote Instance such as AWS EC2
    • Ubuntu
• Run
  • 1. Collator Node without a Relay Chain
    • Manual Sealing
    • Instant Sealing
    • Interval Sealing
  • 2. Collator Node with Local Relay Chain
    • Mixed Terminal/Docker
      • Stop and Clean Environment
    • All in Docker Container
  • Run Tests
    • E2E Tests
  • Run Benchmarks
  • Run with offchain features
• Format, Lint and Audit Source Code
• Runtime
  • Verify Runtime
  • Local Runtime Upgrade
    • Local Relay Chain
    • Standalone Chain (No Relay)
• Contributing
• Security Issue Reporting
• Additional Resources
• Miscellaneous

1. Docker Engine*
2. Docker Compose

• For Mac users, Docker Desktop engine also installs docker compose environment, so no need to install it separately.

Benchmarks are run on an AWS c6i.4xlarge and recommend collators have generally the same reference hardware specified by Parity for Validators.

Non-Collator nodes may have less power, but low memory configurations may lead to out of memory errors.

1. Install Rust using the official instructions.

2. Check out this repository

3. rust-toolchain.toml specifies the standard toolchain to use. If you have rustup installed, it will automatically install the correct toolchain when you run any cargo command.

4. Running make check will run cargo checks for all Frequency features. This is the recommended way to check your code before committing. Alternatively, you can run following for specific features:

   make check-no-relay
   make check-local
   make check-testnet
   make check-mainnet

5. Build Wasm and native code.

   Note, if you get errors complaining about missing dependencies (protobuf, cmake, yarn, node, jq, etc.) install them with your favorite package manager(e.g. Homebrew on macOS) and re-run the command again.

   rustup update
   cargo clean
   make build

   Above will build Frequency with all features. Alternatively you may run following command to build with specific features:

   make build-no-relay
   make build-local
   make build-testnet
   make build-mainnet

   To build local, rococo/paseo (testnet) or mainnet features respectively.

At this point you should have ./target/debug directory generated locally with compiled project files. (or ./target/release for make build-*-release)

Frequency optionally supports asdf for managing dependencies of the following tools: Install the required plugins for asdf: Please note that if you use rustup, asdf may conflict and cause issues. It is recommended to use one or the other, but not both for rust.

asdf plugin-add rust
asdf plugin-add make
asdf plugin-add cmake https://github.com/srivathsanmurali/asdf-cmake.git

Install the dependency versions declared in .tool-versions

asdf install

NOTE: asdf does not support clang and it needs to be installed separately.

For remote instances running Linux, if you want to check out and build such as on an AWS EC2 instance, the process is slightly different to what is in the Substrate documentation.

1. Upgrade the instance and install missing packages with apt:

sudo apt upgrade
sudo apt upgrade git
sudo apt install —-assume-yes build-essential
sudo apt install --assume-yes clang curl libssl-dev cmake

2. Follow official instructions to install Rust, but select 3. customize the installation, then reply n to Modify PATH variable? (Y/n)
3. Follow steps 6-10 at Substrate: Linux development
4. Proceed with checking out and building Frequency as above.

There are 2 options to run the chain locally:

Note, Running Frequency via following options does not require binary to be built or chain specs to be generated separately, and is programmed within the scripts for simplicity.

1. Collator Node without a relay chain (in manual/instant/interval sealing mode)
2. Collator Node with a local relay chain

This option runs just one collator node without the need for a relay chain.

a. Blocks can be triggered by calling the engine_createBlock RPC

curl http://localhost:9944 -H "Content-Type:application/json;charset=utf-8" -d   '{ \
    "jsonrpc":"2.0", \
    "id":1, \
    "method":"engine_createBlock", \
    "params": [true, true] \
    }'

b. Use the "start-manual" make target to call the RPC Great for testing multiple items in the same block or other block formation tests.

make start-manual

Same as Manual Sealing, but will also automatically trigger the formation of a block whenever a transaction is added to the validated transaction pool. Great for most testing.

make start

Also available as a Docker image: frequencychain/instant-seal-node

docker run --rm -p 9944:9944 -p 30333:30333 frequencychain/instant-seal-node

To stop running chain hit [Ctrl+C] in terminal where the chain was started.

This sealing mode will automatically trigger the formation of a block at a specified interval (default is every 12 seconds.)

make start-interval

This option runs one collator node as local host process and two relay chain validator nodes in each own docker container.

1. Start relay chain validator nodes.

   make start-relay

2. Register a new parachain slot (parachain id) for Frequency. Note, if parachain was previously registered on a running relay chain and no new registration is required, then you can skip the above step.

   make register

3. Start Frequency as parachain. This step will generate genesis/wasm and start the parachain collator.

   make start-frequency

4. Onboard Frequency to the relay chain

   make onboard

1. Off-board Frequency from relay chain: make offboard
2. To stop Frequency running in the terminal: [Ctrl+C]
3. Stop the relay chain. make stop-relay
4. Run to remove unused volumes. make docker-prune
5. Clean up temporary directory to avoid any conflicts with next onboarding: rm -fr /tmp/frequency

❗ Currently does not work on M* series MacOS laptops. See #779

Start:

make start-frequency-docker

Stop:

make stop-frequency-docker

# Run all the tests
make test
# Activate selected features
cargo test --features frequency

To run the end-to-end tests, run make e2e-tests.

make benchmarks

make start-frequency-with-offchain

• Format code with make format according to style guidelines and configurations in rustfmt.toml.

• Lint code with make lint to catch common mistakes and improve your Rust code.

  _Note, if you get errors complaining about the wasm build, then you may need to install the wasm target for rust. You can do this with rustup target add wasm32-unknown-unknown

• Alternatively, run make format-lint to run both at the same time.

• Run make lint-audit to audit Cargo.lock files with cargo-deny for crates with security vulnerabilities reported to the RustSec Advisory Database. See cargo-deny installation instructions

1. Check out the commit at which the runtime was built.
2. Use srtool and srtool-cli to verify the runtime:

   SRTOOL_TAG="1.77.0" srtool build \
           --build-opts="'--features on-chain-release-build,no-metadata-docs,frequency'" \
           --profile=release \
           --package=frequency-runtime \
           --root

To upgrade the runtime, run the following command:

make upgrade-local

make upgrade-no-relay

Interested in contributing? Wonderful! Please check out the information here.

Do you know of an on-chain vulnerability (or possible one) that can lead to economic loss, privacy loss, or instability of the network? Please report it by following the steps mentioned in here.

• Cumulus Project
• Cumulus Tutorials
• Prep Substrate environment for development

# Clean up local docker resources
make docker-prune

# View all listening ports
lsof -i -P | grep -i "listen"

# View ports Frequency node is listening on
lsof -i -P | grep -i "listen" | grep frequency