Skip to content

Commit

Permalink
fix: readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Aman035
Aman035 committed Aug 1, 2024
1 parent 040324e commit 5ef7a44
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 80 deletions.
218 changes: 138 additions & 80 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,91 @@
<h1 align="center">
<a href="https://push.org/#gh-light-mode-only">
<img width='20%' height='10%' src="https://res.cloudinary.com/drdjegqln/image/upload/v1686227557/Push-Logo-Standard-Dark_xap7z5.png">
</a>
<a href="https://push.org/#gh-dark-mode-only">
<img width='20%' height='10%' src="https://res.cloudinary.com/drdjegqln/image/upload/v1686227558/Push-Logo-Standard-White_dlvapc.png">
</a>
</h1>

<p align="center">
<i align="center">Push Protocol is a web3 communication network, enabling cross-chain notifications, messaging and much more for dapps, wallets, and services.🚀</i>
</p>

<h4 align="center">

<a href="https://discord.com/invite/pushprotocol">
<img src="https://img.shields.io/badge/discord-7289da.svg?style=flat-square" alt="discord">
</a>
<a href="https://twitter.com/pushprotocol">
<img src="https://img.shields.io/badge/twitter-18a1d6.svg?style=flat-square" alt="twitter">
</a>
<a href="https://www.youtube.com/@pushprotocol">
<img src="https://img.shields.io/badge/youtube-d95652.svg?style=flat-square&" alt="youtube">
</a>
</h4>

<p align="center">
<img src="https://res.cloudinary.com/drdjegqln/image/upload/v1686230764/1500x500_bhmpkc.jpg" alt="dashboard"/>
</p>

# Push Validator Node

Push Storage Node is a part of Push's Proof of Stake (PoS) chain and is responsible for ensuring the integrity and authenticity of transactions by validating them.

## About Validator Node
## Table of Contents

Validator nodes play a crucial role in the Push Network by ensuring the integrity and authenticity of notifications. Here’s a more technical yet approachable explanation:
- [Overview](#overview)
- [Architecture](#architecture)
- [Installation](#installation)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

**What is a Validator Node?**
A validator node in the Push Network is responsible for validating notifications before they are distributed across the network. These nodes are essential for maintaining the security and reliability of the network.
## Overview
Push Validator Nodes are responsible for validating txs that are generated on Push Network. These types of nodes ensure validity of a tx that is generated by validating the signer of the tx. They also ensure that either the wallet that generates the tx or a delegate has enough fees to cover the tx.

**How Does It Work?**
1. Staking Requirement:
## Architecture

### Staking Requirement
To operate a validator node, participants must stake a certain amount of tokens. This staking process serves as a security deposit, ensuring that validators act in the network's best interest.

2. Validation Process:
When a notification is generated, the Push Network’s SDK randomly selects one validator node to verify the notification's authenticity and correctness.
After the initial verification, the notification is sent to three other randomly chosen validators for attestation. This ensures a consensus is reached and minimizes the risk of a single validator acting maliciously.
### Validation Process
1. When a transaction is generated, the Push Network’s SDK / client pings a random Validator `Vx` which returns another random validator `Vy` and an attestation token.
2. Client sends the transaction to `Vy` along with the attestation token. ( Attestation token is a time based token that is generated by `Vx` to provide ability to client to send a transaction to `Vy` )
3. `Vy` validates the transaction on basis od several parameters like ( These are just for reference, actual parameters may vary ):
- Is the transaction signed by the correct signer?
- Does the signer have enough fees to cover the transaction?
- Is the transaction valid?
- Is the transaction within the network's rules?
4. Once the transaction is validated, `Vy` processes this transaction to be attached to a block.
5. The block is attested by N number of validators and is marked as approved or rejected based on the majority vote.

### Quorum
A quorum is the minimum number of validator approvals required for a block to be verified. It is decided by the smart contract `validator.sol` and can be changed by the network's governance process.

3. Quorum and Attestation:
A quorum is the minimum number of validator approvals required for a notification to be considered verified. Once this quorum is met, the notification is marked as verified.
### Storage and Indexing
After the block is validated, it is stored in the queue storage of the validator node. Blocks are picked up from this queue by storage nodes who store and index them.

4. Storage and Indexing:
After the notification is validated, it is stored in the queue storage of the validator node which then can be fetched by the storage nodes to index and deliver notification.
![Network Interaction](assets/nodeInteraction.jpg)

**Security Mechanisms**
### Security Mechanisms
1. Slashing:
If a validator node is found to be acting maliciously—such as approving fraudulent notifications—the network can penalize the validator by slashing a portion of their staked tokens. This penalty deters malicious activity and ensures that validators have a financial incentive to act honestly.
2. Random Selection:
The random selection of validators for both the initial verification and subsequent attestation adds an extra layer of security. It prevents collusion among validators and ensures that the validation process remains fair and unbiased.

![Slashing](assets/slashing.jpg)

## Project Setup Guide
## Installation

⚠️ **Warning: Work In Progress** ⚠️

### Pre-Installation Requirements
This project is currently a work in progress. Please be aware that things might break, and the installation process might change as we improve and dockerize it completely for public running of the node. Proceed with caution and check back frequently for updates.

### Pre-Installation Requirements

Before starting, ensure you have the following tools installed:



1. **NVM (Node Version Manager)** - [Install NVM on macOS using Homebrew](https://tecadmin.net/install-nvm-macos-with-homebrew/)

2. **Node.js versions 18 & 20** - Needed for different parts of the project (switch between them using `nvm`).
Expand All @@ -57,39 +101,13 @@ Before starting, ensure you have the following tools installed:

### Pre-Installation Requirements

1. **Install Node.js versions**:
```bash

# For Hardhat (to prevent warnings)

nvm install 18

# For development (anything works)
### Prerequisites

nvm install 20

# Switch to the latest Node.js version

nvm use 20

```



2. **Verify installed versions (approximates are fine)**:
```bash

nvm --version # Expected output: 0.39.1

node --version # Expected output: v20.6.1

npm --version # Expected output: 9.8.1

yarn --version # Expected output: 1.22.19

```
- [Node.js](https://nodejs.org/) (>= 16)
- [Docker](https://www.docker.com/)
- [Yarn](https://yarnpkg.com/)

3. **Using `do.sh`**
### Setup `do.sh` Script
The `do.sh` script is included inside the **`zips`** folder. It provides shortcuts for running various commands, including publishing a default test key and executing Hardhat with arguments. Ensure you review the code before executing any commands.

- **Setting up `do.sh`**
Expand Down Expand Up @@ -127,13 +145,23 @@ The `do.sh` script is included inside the **`zips`** folder. It provides shortcu
do command1 command2 command3
```

### Validator Nodes (Also called V Nodes)
### Running the Node

1. **Install the dependencies:**
```bash
yarn install
```
2. **Configure docker directories:**

1. Clone the repository:

```bash
git clone https://github.com/push-protocol/push-vnode.git
cd push-vnode
```

2. Install dependencies:

```bash
yarn install
```

2. Configure docker directories:
To set up the validator nodes, you'll need to configure specific directories for each node. This setup ensures that each node runs independently with its own environment and key files.
- Download and Unpack Docker Directory:
Expand All @@ -145,21 +173,32 @@ Each node directory (e.g., docker/01, docker/02, docker/03) contains the necessa
**validator_eth_key.json**: This file holds the Ethereum key for the validator node. The key is password-encrypted to ensure security. This key is essential for the node to sign and validate transactions on the network.
**History Fetcher Configuration:** For demonstration purposes, the history fetcher is turned off. This means that the nodes will not retrieve or process historical data, which simplifies the setup and reduces resource consumption during testing.
3. **MySQL Database Setup:**
For the nodes to function correctly, you need to set up three separate MySQL databases, one for each node. These databases will store the data related to each validator node.
- Access the MySQL command-line interface by running the following command in your terminal:
4. Start the docker container:
```bash
docker-compose up
```
> **Note:** It is expected that after this command you would have the following containers running: **postgres, redis, ipfs**
5. Database Setup:
For the nodes to function correctly, you need to set up three separate databases, one for each node. These databases will store the data related to each validator node.
<!-- - Access the MySQL command-line interface by running the following command in your terminal:
```bash
mysql -u root -p PASSWORD=pass
```
- Once you're in the MySQL CLI, create each of the databases by running the following commands:
```bash
CREATE DATABASE vnode1 CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE DATABASE vnode2 CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE DATABASE vnode3 CHARACTER SET utf8 COLLATE utf8_general_ci;
-->
```
- Run the nodes in separate terminals:
- Create each of the databases by running the following commands:
```bash
CREATE DATABASE vnode1 CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE DATABASE vnode2 CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE DATABASE vnode3 CHARACTER SET utf8 COLLATE utf8_general_ci;
```
6. Run the nodes in separate terminals:
```bash
# Run Validator Node 1
do debug.v1
Expand All @@ -170,24 +209,28 @@ For the nodes to function correctly, you need to set up three separate MySQL dat
# Run Validator Node 3
do debug.v3
```
- After starting the nodes, you can add mock data to each database to simulate channel subscriptions. This helps in syncing with the local EVM for demonstration purposes.
```shell
INSERT INTO channels (channel, ipfshash, name, info, url, icon, processed, attempts, alias_address, alias_blockchain_id, is_alias_verified, blocked, alias_verification_event, activation_status, verified_status, subgraph_details, subgraph_attempts, counter, timestamp, channel_settings)
VALUES ('eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', 'QmTX8zZjzuKpiLZmn4ShNzyKDakNdbBQfwi449TBw7wgoK', 'testing goerli', 'Testing', 'https://dev.push.org/', 'https://gateway.ipfs.io/ipfs/bafybeidkt3qrlcplntabfazs7nnzlxdzu36mmieth2ocyphm2kp4sh333a/QmTX8zZjzuKpiLZmn4ShNzyKDakNdbBQfwi449TBw7wgoK', 1, 0, 'NULL', 'NULL', 0, 0, null, 1, 0, null, 0, null, '2023-08-11 13:45:05', null);
7. Mocking Data ( Optional )
After starting the nodes, you can add mock data to each database to simulate channel subscriptions. This helps in syncing with the local EVM for demonstration purposes.
> **Note:** Skip this if you are not using the local EVM.
```shell
INSERT INTO channels (channel, ipfshash, name, info, url, icon, processed, attempts, alias_address, alias_blockchain_id, is_alias_verified, blocked, alias_verification_event, activation_status, verified_status, subgraph_details, subgraph_attempts, counter, timestamp, channel_settings)
VALUES ('eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', 'QmTX8zZjzuKpiLZmn4ShNzyKDakNdbBQfwi449TBw7wgoK', 'testing goerli', 'Testing', 'https://dev.push.org/', 'https://gateway.ipfs.io/ipfs/bafybeidkt3qrlcplntabfazs7nnzlxdzu36mmieth2ocyphm2kp4sh333a/QmTX8zZjzuKpiLZmn4ShNzyKDakNdbBQfwi449TBw7wgoK', 1, 0, 'NULL', 'NULL', 0, 0, null, 1, 0, null, 0, null, '2023-08-11 13:45:05', null);
INSERT INTO subscribers (is_currently_subscribed, channel, alias, subscriber, signature, timestamp, sub_timestamp, unsub_timestamp, user_settings)
VALUES (1, 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', null, 'eip155:0x5ac9E6205eACA2bBbA6eF716FD9AabD76326EEee', 'eip155:5:0xba3f4df977fc09614e86c84ab4857ce9b113d52dde258aedfa263fc29018f611', '2022-10-04 08:10:12', '2022-10-04 08:10:12', null, 'null');
INSERT INTO subscribers (is_currently_subscribed, channel, alias, subscriber, signature, timestamp, sub_timestamp, unsub_timestamp, user_settings)
VALUES (1, 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', null, 'eip155:0x5ac9E6205eACA2bBbA6eF716FD9AabD76326EEee', 'eip155:5:0xba3f4df977fc09614e86c84ab4857ce9b113d52dde258aedfa263fc29018f611', '2022-10-04 08:10:12', '2022-10-04 08:10:12', null, 'null');
INSERT INTO subscribers (is_currently_subscribed, channel, alias, subscriber, signature, timestamp, sub_timestamp, unsub_timestamp, user_settings)
VALUES (1, 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', null, 'eip155:0x69e666767Ba3a661369e1e2F572EdE7ADC926029', 'eip155:5:0xc5147c36467f489c212460e01dfd1ede1d853d67d17c042e994100b89a0d5a9d', '2022-10-20 12:27:48', '2022-10-20 12:27:48', null, 'null');
INSERT INTO subscribers (is_currently_subscribed, channel, alias, subscriber, signature, timestamp, sub_timestamp, unsub_timestamp, user_settings)
VALUES (1, 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', null, 'eip155:0x69e666767Ba3a661369e1e2F572EdE7ADC926029', 'eip155:5:0xc5147c36467f489c212460e01dfd1ede1d853d67d17c042e994100b89a0d5a9d', '2022-10-20 12:27:48', '2022-10-20 12:27:48', null, 'null');
INSERT INTO subscribers (is_currently_subscribed, channel, alias, subscriber, signature, timestamp, sub_timestamp, unsub_timestamp, user_settings)
VALUES (1, 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', null, 'eip155:0xD8634C39BBFd4033c0d3289C4515275102423681', 'eip155:5:0xba3f4df977fc09614e86c84ab4857ce9b113d52dde258aedfa263fc29018f611', '2022-10-04 08:10:12', '2022-10-04 08:10:12', null, 'null');
INSERT INTO subscribers (is_currently_subscribed, channel, alias, subscriber, signature, timestamp, sub_timestamp, unsub_timestamp, user_settings)
VALUES (1, 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', null, 'eip155:0xD8634C39BBFd4033c0d3289C4515275102423681', 'eip155:5:0xba3f4df977fc09614e86c84ab4857ce9b113d52dde258aedfa263fc29018f611', '2022-10-04 08:10:12', '2022-10-04 08:10:12', null, 'null');
```
```
## Testing the node with CURL
## Testing
### Testing the node with CURL
1. Get a validator Token
**Request:**
Expand Down Expand Up @@ -219,3 +262,18 @@ For the nodes to function correctly, you need to set up three separate MySQL dat
curl --location 'http://localhost:4001/apis/v1/messaging/settings/eip155:11155111:0xD8634C39BBFd4033c0d3289C4515275102423681/ETH_TEST_GOERLI'
```
## Contributing
We welcome contributions from the community! To contribute, please follow these steps:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature-name`).
3. Make your changes and commit them (`git commit -m 'Add some feature'`).
4. Push to the branch (`git push origin feature/your-feature-name`).
5. Open a pull request.
Please ensure your code adheres to our coding standards and includes appropriate tests.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Binary file added assets/nodeInteraction.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/slashing.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 5ef7a44

Please sign in to comment.