Metadata-Version: 2.1
Name: pantos-validator-node
Version: 1.8.2
Summary: Pantos Validator Node (reference implementation)
License: GPL-3.0-only
Author: Pantos GmbH
Author-email: contact@pantos.io
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: pantos-common (==2.1.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: alembic (==1.13.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: celery (==5.3.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: cerberus (==1.3.4) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: flask (==3.0.3) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: flask-cors (==4.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: flask-restful (==0.3.10) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: marshmallow (==3.21.3) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: psycopg2-binary (==2.9.9) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pyyaml (==6.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: sqlalchemy (==2.0.31) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: web3 (==6.5.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: json-log-formatter (==0.5.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pyaml-env (==1.2.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: python-dotenv (==1.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: semantic-version (==2.10.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: requests (==2.32.3) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: hexbytes (==1.2.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: flower (==2.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: gunicorn (==22.0.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: types-requests (==2.32.0.20240712) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: types-sqlalchemy (==1.4.53.38) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: aiohttp (==3.9.5) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: aiosignal (==1.3.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: amqp (==5.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: aniso8601 (==9.0.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: annotated-types (==0.7.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: async-timeout (==4.0.3) ; python_version >= "3.10" and python_version < "3.11"
Requires-Dist: attrs (==23.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: billiard (==4.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: bitarray (==2.9.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: blinker (==1.8.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: certifi (==2024.7.4) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: charset-normalizer (==3.3.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: ckzg (==1.0.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: click (==8.1.7) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: click-didyoumean (==0.3.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: click-plugins (==1.1.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: click-repl (==0.3.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: colorama (==0.4.6) ; python_version >= "3.10" and python_version < "4.0" and platform_system == "Windows"
Requires-Dist: cytoolz (==0.12.3) ; python_version >= "3.10" and python_version < "4" and implementation_name == "cpython"
Requires-Dist: eth-abi (==5.1.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-account (==0.13.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-hash (==0.7.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-keyfile (==0.8.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-keys (==0.4.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-rlp (==2.1.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-typing (==3.5.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: eth-utils (==2.3.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: frozenlist (==1.4.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: idna (==3.7) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: itsdangerous (==2.2.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: jinja2 (==3.1.4) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: jsonschema (==4.23.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: jsonschema-specifications (==2023.12.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: kombu (==5.3.7) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: lru-dict (==1.3.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: markupsafe (==2.1.5) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: multidict (==6.0.5) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: parsimonious (==0.10.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: prompt-toolkit (==3.0.47) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: protobuf (==5.27.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pycryptodome (==3.20.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pydantic (==2.8.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: pydantic-core (==2.20.1) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: python-dateutil (==2.9.0.post0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pytz (==2024.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: pywin32 (==306) ; python_version >= "3.10" and python_version < "4.0" and platform_system == "Windows"
Requires-Dist: referencing (==0.35.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: regex (==2024.5.15) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: rlp (==3.0.0) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: rpds-py (==0.19.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: setuptools (==70.3.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: six (==1.16.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: toolz (==0.12.1) ; python_version >= "3.10" and python_version < "4" and (implementation_name == "pypy" or implementation_name == "cpython")
Requires-Dist: typing-extensions (==4.12.2) ; python_version >= "3.10" and python_version < "4"
Requires-Dist: tzdata (==2024.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: urllib3 (==2.2.2) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: vine (==5.1.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: wcwidth (==0.2.13) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: websockets (==12.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: werkzeug (==3.0.3) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: yarl (==1.9.4) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: mako (==1.3.5) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: packaging (==24.1) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: greenlet (==3.0.3) ; python_version < "3.13" and (platform_machine == "aarch64" or platform_machine == "ppc64le" or platform_machine == "x86_64" or platform_machine == "amd64" or platform_machine == "AMD64" or platform_machine == "win32" or platform_machine == "WIN32") and python_version >= "3.10"
Requires-Dist: humanize (==4.10.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: prometheus-client (==0.20.0) ; python_version >= "3.10" and python_version < "4.0"
Requires-Dist: tornado (==6.4.1) ; python_version >= "3.10" and python_version < "4.0"
Description-Content-Type: text/markdown

<img src="https://raw.githubusercontent.com/pantos-io/validatornode/img/pantos-logo-full.svg" alt="Pantos logo" align="right" width="120" />

[![CI](https://github.com/pantos-io/validatornode/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/pantos-io/validatornode/actions/workflows/ci.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=pantos-io_validatornode&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=pantos-io_validatornode)



# Pantos Validator Node (reference implementation)

## 1. Introduction

### 1.1 Overview

Welcome to the documentation for Pantos Validator Node. 

The Pantos Validator Node is responsible for validating cross-chain transfers on behalf of the users. To initiate a cross-chain token transfer, a client has to send a signed request to a service node. To find an appropriate service node, the client can query the PantosHub contract of the source blockchain. To enable this, each service node registers itself at the PantosHub contract of each source blockchain supported by the service node.

### 1.2 Features

The Pantos Validator Node is split into two applications:

#### Web server application

The web server application is responsible for the following:

1. Serving signed (by the service node) bids.
2. Accepting signed (by the user) transfer requests.

#### Celery application

The celery application is responsible for the following:

1. Updating the bids later served to the user through the web application.
2. Submitting the signed transfer requests to the source blockchain.

## 2. Installation

### IMPORTANT ###

We provide two ways to modify the app configuration, either through `validator-node-config.env` or `validator-node-config.yml`. We recommend using the `.env` file, as the `.conf` file is overwritten on every install.

While using the `.env` file you need to be aware that any fields containing certain special characters need to be wrapped around single quotes (e.g. `ETHEREUM_PRIVATE_KEY_PASSWORD='12$$#%R^'`).

The application will complain on startup should the configuration be incorrect.

### 2.1 Pre-built packages

There are two ways to install the apps using pre-built packages:

#### Debian package distribution

We provide Debian packages alongside every release, you can find them in the [releases tab](https://github.com/pantos-io/validatornode/releases). Further information on how to use the service node packages can be found [here](https://pantos.gitbook.io/technical-documentation/general/validator-node).

We have a PPA hosted on GitHub, which can be accessed as follows:

```bash
curl -s --compressed "https://pantos-io.github.io/validatornode/KEY.gpg" | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/validatornode.gpg >/dev/null
sudo curl -s --compressed -o /etc/apt/sources.list.d/pantos-validatornode.list "https://pantos-io.github.io/validatornode/pantos-validatornode.list"
sudo apt update
sudo apt install pantos-validator-node
```

#### Docker images

We also distribute docker images in DockerHub with each release. These are made available under the pantosio project as either [**app**](https://hub.docker.com/r/pantosio/validator-node-app) or [**worker**](https://hub.docker.com/r/pantosio/validator-node-worker).

You can run a local setup with docker by doing the following steps:

- Enable swarm mode with `docker swarm init`. This is required because we're using the `overlay` network driver.
- The variables `DB_URL`, `CELERY_BACKEND` and `CELERY_BROKER` are already defined in the `docker-compose.yml`
- Modify the `.env` file to match your current setup
- Ensure you have a `keystore` file located in the same directory
- Run `docker compose up`

Please note that you may need to add a load balancer or another webserver in front of this setup should you want to host this setup under a specific domain.

If you're hosting this on a cloud provider (AWS, GCP, Azure or alike), these are normally provided. You just need to point the load balancer to the port exposed by the app, `8080`, and configure the rest accordingly.

#### Multiple local deployments using docker swarm

We support multiple local deployments, for example for testing purposes, using docker swarm. To get started you need to enable swarm mode (if you haven't) by running:

`docker swarm init`

Then you can run the stacks like this:

`make docker-multiple INSTANCE_COUNT=<number of instances>`

To remove all the stacks, run the following:

`make docker-remove`

Please note that this mode uses an incremental amount of resources and that Docker Desktop doesn't fully support displaying it, but it should be good enough to test multi-sig locally.

**IMPORTANT** If you want to switch between this mode and docker compose you **must** remove the counterpart by using `docker compose down -v` or `make docker-remove` respectively.

#### Python package

We distribute the package in test-pypi and pypi under the following projects: https://test.pypi.org/project/pantos-validator-node/ and https://pypi.org/project/pantos-validator-node/. You can install it to your project by using `pip install pantos-validator-node`.

### 2.2  Prerequisites

Please make sure that your environment meets the following requirements:

#### Python Version

The Pantos Service Node supports **Python 3.10** or higher. Ensure that you have the correct Python version installed before the installation steps. You can download the latest version of Python from the official [Python website](https://www.python.org/downloads/).

#### Library Versions

The Pantos Service Node has been tested with the library versions specified in **poetry.lock**.

#### Poetry

Poetry is our tool of choice for dependency management and packaging.

Installing: 
https://python-poetry.org/docs/#installing-with-the-official-installer
or
https://python-poetry.org/docs/#installing-with-pipx

By default poetry creates the venv directory under under ```{cache-dir}/virtualenvs```. If you opt for creating the virtualenv inside the project’s root directory, execute the following command:
```bash
poetry config virtualenvs.in-project true
```

### 2.2  Installation Steps

#### Libraries

Create the virtual environment and install the dependencies:

```bash
$ poetry install --no-root
```

#### Pre-commit

In order to run pre-commit before a commit is done, you have to install it:

```bash
pre-commit install --hook-type commit-msg -f && pre-commit install
```

Whenever you try to make a commit, the pre-commit steps are executed.

## 3. Usage

### 3.1 Format, lint and test

Run the following command from the repository's root directory:

```bash
make code
```

### 3.2 Local development environment

#### PostgreSQL

Launch the PostgreSQL interactive terminal:

```bash
sudo -u postgres psql
```

Create a Service Node user and three databases:

```
CREATE ROLE "pantos-validator-node" WITH LOGIN PASSWORD '<PASSWORD>';
CREATE DATABASE "pantos-validator-node" WITH OWNER "pantos-validator-node";
CREATE DATABASE "pantos-validator-node-celery" WITH OWNER "pantos-validator-node";
CREATE DATABASE "pantos-validator-node-test" WITH OWNER "pantos-validator-node";
```

#### RabbitMQ

Create a Service Node user and virtual host:

```
sudo rabbitmqctl add_user pantos-validator-node <PASSWORD>
sudo rabbitmqctl add_vhost pantos-validator-node
sudo rabbitmqctl set_permissions -p pantos-validator-node pantos-validator-node ".*" ".*" ".*"
```

## 4. Contributing

For contributions take a look at our [code of conduct](CODE_OF_CONDUCT.md).

