{"id":29040661,"url":"https://github.com/pushchain/push-vnode","last_synced_at":"2025-06-26T14:36:35.761Z","repository":{"id":267925386,"uuid":"836727865","full_name":"pushchain/push-vnode","owner":"pushchain","description":"Push Validator 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.","archived":false,"fork":false,"pushed_at":"2025-03-27T18:13:57.000Z","size":1924,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-23T13:54:07.485Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pushchain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-01T12:41:03.000Z","updated_at":"2025-03-27T18:14:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"48148f2e-feb8-4eb9-978d-ffed18ecc2fb","html_url":"https://github.com/pushchain/push-vnode","commit_stats":null,"previous_names":["push-protocol/push-vnode","pushchain/push-vnode"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pushchain/push-vnode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-vnode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-vnode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-vnode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-vnode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pushchain","download_url":"https://codeload.github.com/pushchain/push-vnode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushchain%2Fpush-vnode/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262085898,"owners_count":23256540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-26T14:36:32.706Z","updated_at":"2025-06-26T14:36:35.751Z","avatar_url":"https://github.com/pushchain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003ca href=\"https://push.org/#gh-light-mode-only\"\u003e\n    \u003cimg width='20%' height='10%' src=\"https://res.cloudinary.com/drdjegqln/image/upload/v1686227557/Push-Logo-Standard-Dark_xap7z5.png\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://push.org/#gh-dark-mode-only\"\u003e\n    \u003cimg width='20%' height='10%' src=\"https://res.cloudinary.com/drdjegqln/image/upload/v1686227558/Push-Logo-Standard-White_dlvapc.png\"\u003e\n    \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ci align=\"center\"\u003ePush protocol is evolving to Push Chain, a shared-state L1 designed to deliver universal app experiences (Any Chain. Any User. Any App).🚀\u003c/i\u003e\n\u003c/p\u003e\n\n\u003ch4 align=\"center\"\u003e\n\n  \u003ca href=\"https://discord.com/invite/pushprotocol\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/discord-7289da.svg?style=flat-square\" alt=\"discord\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/pushprotocol\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/twitter-18a1d6.svg?style=flat-square\" alt=\"twitter\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.youtube.com/@pushprotocol\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/youtube-d95652.svg?style=flat-square\u0026\" alt=\"youtube\"\u003e\n  \u003c/a\u003e\n\u003c/h4\u003e\n\n# Push Validator Node\n\nPush Validator 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.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Installation](#installation)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n- [Docker](#Docker-env-setup)\n\n## Overview\n\nPush 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.\n\n## Architecture\n\n### Staking Requirement\n\nTo 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.\n\n### Validation Process\n\n1. 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.\n2. 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` )\n3. `Vy` validates the transaction on basis od several parameters like ( These are just for reference, actual parameters may vary ):\n   - Is the transaction signed by the correct signer?\n   - Does the signer have enough fees to cover the transaction?\n   - Is the transaction valid?\n   - Is the transaction within the network's rules?\n4. Once the transaction is validated, `Vy` processes this transaction to be attached to a block.\n5. The block is attested by N number of validators and is marked as approved or rejected based on the majority vote.\n\n### Quorum\n\nA 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.\n\n### Storage and Indexing\n\nAfter 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.\n\n![Network Interaction](wiki/nodeInteraction.jpg)\n\n### Security Mechanisms\n\n1. Slashing:\n   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.\n2. Random Selection:\n   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.\n\n![Slashing](wiki/slashing.jpg)\n\n## Docker env setup\n\n**FOR local testing**\n\nAssumptions:\n\n- default dir is /Users/w/chain where all push git repos are located (you can use any)\n- checkout every project (main branch)\n  - /Users/w/chain/push-network-sdk\n  - /Users/w/chain/push-node-smart-contracts\n  - /Users/w/chain/push-vnode\n  - /Users/w/chain/push-snode\n  - /Users/w/chain/push-anode\n- docker and docker-compose are installed\n- docker desktop case: Allow full docker image access to /Users/w/chain in Preferences-\u003eResources-\u003eFile sharing\n- recommended docker version could look like this (no specific version is needed; )\n- naming conventions:\n  - docker images: hardhat-main, validator-main, ...\n  - docker containers: vnode1, vnode2, ...\n  - docker dns: vnode1.local, redis.local, hardhat.local, ....\n\n```shell\ndocker --version\nDocker version 20.10.21, build baeda1f\n\ndocker compose version\nDocker Compose version v2.13.0\n\npython3 --version\nPython 3.11.6\n```\n\nSetup docker images for smart-contracts \u0026 vnodes\n\n```bash\n## create docker network\ndocker network create push-dev-network\n## prepare image for hardhat\ncd /Users/w/chain/push-node-smart-contracts\ndocker build . -t hardhat-main\n\n## prepare image for V (if needed)\ncd /Users/w/chain/push-vnode\ndocker build . -t vnode-main\n\n## prepare image for S (if needed)\ncd /Users/w/chain/push-snode\ndocker build . -t snode-main\n\n## prepare image for A (if needed)\ncd /Users/w/chain/push-anode\ndocker build -t anode-main -f Dockerfile.light .\n```\n\nRun\n\n```bash\ncd /Users/w/chain/push-vnode/docker\n\n## run evm (hardhat test vm)\ndocker compose -f evm.yml up -d\n\n## run mysql + postgres + redis + phpmyadmin\n\n# run dbs\ndocker compose -f db.yml up -d\n## hints:\n## read logs:                         db.yml logs -f\n## re-create container (non-existing) db.yml up -d\n## start (existing)                   db.yml start\n## stop  (existing)                   db.yml stop\n## delete container:                  db.yml down\n## delete everything:                 ./cleanup.sh\n\n## run vnode1 + vnode2 + vnode3\ndocker compose -f v.yml up -d\n\n## run snode1 + snode2\ndocker compose -f s.yml up -d\n\n## run anode1\ndocker compose -f a.yml up -d\n\n```\n\nCheck that all docker DNS is online (OPTIONAL)\n\n```bash\ndocker exec redis bash -c \" getent hosts redis.local \"\ndocker exec redis bash -c \" getent hosts mysql.local \"\ndocker exec redis bash -c \" getent hosts phpmyadmin.local \"\ndocker exec redis bash -c \" getent hosts hardhat.local \"\ndocker exec redis bash -c \" getent hosts vnode1.local \"\ndocker exec redis bash -c \" getent hosts vnode2.local \"\ndocker exec redis bash -c \" getent hosts vnode3.local \"\n```\n\nTest vnodes: vnode1, snode2, vnode3 are online and visible from the host machine\n\n```shell\n##\ncurl --location 'http://localhost:4001/api/v1/rpc/' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"push_listening\",\n    \"params\": [],\n    \"id\": 1\n}'\necho ------------\ncurl --location 'http://localhost:4002/api/v1/rpc/' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"push_listening\",\n    \"params\": [],\n    \"id\": 2\n}'\necho ------------\ncurl --location 'http://localhost:4003/api/v1/rpc/' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"push_listening\",\n    \"params\": [],\n    \"id\": 3\n}'\necho ------------\n```\n\nTest vnodes: Smoke-test validator api\n\n```shell\n### 1 send a test transaction (DUMMY DATA) (INCLUDES API TOKEN)\n\n```\n\nTest vnodes: Smoke test api token\n\n```sh\n### 1 get api token\ncurl --location 'http://localhost:4001/api/v1/rpc/' \\\n--header 'Content-Type: application/json' \\\n--data '{\n\"jsonrpc\": \"2.0\",\n\"method\": \"push_getApiToken\",\n\"params\": [],\n\"id\": 1\n}'\necho ------------\n```\n\nTest anodes: Get blocks\n\n```shell\ncurl --location 'http://localhost:5001/rpc' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"RpcService.getBlocks\",\n    \"params\": {\n        \"startTime\": 1724771470,\n        \"direction\": \"DESC\",\n        \"showDetails\": true,\n        \"pageSize\": 10,\n        \"page\": 1\n    },\n    \"id\": 1\n}'\n```\n\nTest with an SDK:\n\n```shell\ncd /Users/w/chain/push-network-sdk\n\n# edit file\ncode packages/core/tests/validator/backend-smoke-test.test.ts\n```\n\nreplace\n\n```ts\nconst env = config.ENV\n```\n\nwith\n\n```ts\nconst env = 'local'\n```\n\nin order to query local docker instead of DEV env.\n\n- now you can run it via IDE or from a console\n\n```shell\n# setup sdk\ncd /Users/w/chain/push-network-sdk\n\nnpm install\n\ncd packages/core\n\nnpm install\n\n# todo check how to run this file with the correct cmd param\nnx run core:test --testFile=packages/core/tests/validator/backend-smoke-test.test.ts\n\n```\n\n## Licenses\n\nAll crates of this repository are licensed under either of\n\n- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushchain%2Fpush-vnode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpushchain%2Fpush-vnode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushchain%2Fpush-vnode/lists"}