Orcfax Validator Node API

Provides a web-socket for Orcfax nodes to connect to.

Configuration

Configuration is done via a TOML file which needs to be passed to the validator environment as VALIDATOR_CONFIG.

The example config shows the different key-value pairs required to initialize and run the validator.

Running locally

After configuring the environment and creating a virtual environment and installing the dependencies run python -m src.validator_node_api.validator_node.

You can wrap this in a shell script as follows:

#! /usr/bin/bashexport VALIDATOR_CONFIG=config.toml
/path/to/venv/bin/python -m src.validator_node_api.validator_node

Running in production

A package must be generated from this code using the justfile and an appropriate tag. Tag data from source control is used to generate the archival audit package.

Once a package has been created and installed in a virtual environment it can be run with a command such as: /path/to/venv/bin/validator-node. This can also be weapped in a shell script to make it easier to do.

Connecting a collector node

Connections to the validator are normally through the web-socket address:

wss://<validator-url>/ws/node/<node-id>/

Including trailing slash /, and where <node-id> is some form of identifier that is persistent with an Orcfax collector.

Functionality

• Receives messages from Orcfax collectors.
• Actions validation requests from outside.
• Validates the most current messages.
• Broadcasts results to:
  • The fact explorer.
  • Cardano Open Oracle Protocol.
  • Monitoring tools.
• Sends a packaging request to Arkly to archive the data produced during validation.

Testing and linting

• python -m tox -e py3
• python -m tox -e linting

Running individual tests

Tests can take some time. To run test files individually:

• python -m tox -e py3 -- tests/<test_file>.py

To run tests individually, specify the test name with ::,

• python -m tox -e py3 -- tests/<test_file>.py::<test_name>

Upgrading dependencies

pip-upgrader is part of the local dependencies. To upgrade run the below command and follow the prompts:

pip upgrade

Securing the validator

The web-sockets should be secured in a production instance. The private key and certificate file should be stored in ./certs.

Creating a self-signed private key and certificate

For local development you may want to create a locally self-signed key and certificate. Instructions for doing that are below.

Configuration file

You will need a configuration file as follows. Fill in the blanks with your system's country, locality, admin, etc. The next step will fail to encode this data if it is unexpectedly too-short or too-long, i.e. incorrectly filled in.

[req]
default_bits = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
countryName =
stateOrProvinceName =
localityName =
organizationName =
commonName = 127.0.0.1: Self-signed certificate
emailAddress=
[req_ext]
subjectAltName = @alt_names
[v3_req]
subjectAltName = @alt_names
[alt_names]
IP.1 = 127.0.0.1

Create the private-key certificate pair

openssl req -x509 \
-nodes \
-days 365 \
-newkey rsa:2048 \
-keyout server.key \
-out server.crt \
-config cert.cfg

Inspect the values

On success your should be able to see your details in the generated certificate.

• openssl x509 -in server.crt -text -noout | less

The certificate file is what is shared with nodes connecting to the validator.

More information

For more information I used this helpful article on Medium by Dimitri Witkowski: How to generate a self-signed SSL certificate for an IP address

Developer tools

This repository comes with a number of helper scripts:

• fetch_and_store.py.
• send_validation_request.py.
• wait_for_validator_messages.py.

These scripts help with testing real-time validation, and message sending over websocket.

The scripts can be run using default arguments to connect over ssl with no configuration. Testing over ssl is default. If local secure sockets are desired then for local testing use the --secure-local flag. To test without ssl use --local.

Local configuration of helpers

Some of the configuration may still need to be completed locally, such as providing node addresses in fetch_and_store.py script. To prevent git from recognizing these as modified, use make hide-config to mask these changes. To stage changes after doing this run make show-config and the files can be added to git as before.