kryvora-node README

The project's README from github.com/kryvora-network/kryvora-node. As one markdown file: README.md.

kryvora-node

Go Version License Release CI Status Network

Official client daemon for Kryvora Network nodes.

Overview

Kryvora is a decentralized physical infrastructure network designed for distributed verification and worker coordination. The kryvora-node daemon connects worker hardware to the Kryvora Hub, executes telemetry probes, verifies peer state, and reports proof of availability.

System Topology

+-------------------------------------------------------------+
|                     Kryvora Node Host                       |
|                                                             |
|  +--------------------+             +--------------------+  |
|  |   Worker Engine    |             |  Telemetry Daemon  |  |
|  |  (Task Execution)  |<----------->|    (Port 4177)     |  |
|  +---------+----------+   IPC/Bus   +---------+----------+  |
|            |                                  |             |
|            | Unix Socket (/var/run/node.sock) | HTTP API    |
|            v                                  v             |
|  +-------------------------------------------------------+  |
|  |                 Kryvora Storage Store                 |  |
|  |            (State, Peer Nonces, Telemetry)            |  |
|  +-------------------------------------------------------+  |
+------------------------------+------------------------------+
                               |
                   Mutual TLS  |  Heartbeat (30s)
                   gRPC / HTTP |  Verification Probes
                               v
+-------------------------------------------------------------+
|                 Kryvora Coordination Hub                    |
|                        (Port 4188)                          |
+-------------------------------------------------------------+

Node Licensing & Genesis Key Requirement

Operating a Kryvora verification node requires an active Genesis Node Key. The Genesis Node Key is an on-chain soulbound verification credential deployed on Arbitrum One:

Before launching the daemon, obtain your node bootstrap token by connecting your wallet at node.kryvora.network. Unauthenticated nodes without a valid bootstrap token will be rejected by the Coordination Hub (hub.kryvora.network:4188).

System Requirements

Hardware specs for running a standard verification worker:

Quick Start

Option 1: Automated Script (Linux systemd)

Run the installation script to fetch the binary and register the systemd service:

curl -sSL https://raw.githubusercontent.com/kryvora-network/kryvora-node/main/install.sh | bash

The script will prompt for your Genesis Node Key bootstrap token and register the systemd service.

Check service status:

sudo systemctl status kryvora-node

Option 2: Docker Compose

  1. Clone the repository:
git clone https://github.com/kryvora-network/kryvora-node.git
cd kryvora-node
  1. Copy the configuration template and set your token:
cp config.example.yaml config.yaml
# Edit config.yaml and insert your bootstrap_token under auth:
# Or set KRYVORA_BOOTSTRAP_TOKEN in your environment
  1. Start the node container:
KRYVORA_BOOTSTRAP_TOKEN="your_token_here" docker compose up -d
  1. Verify logs:
docker compose logs -f kryvora-node

Option 3: Build from Source

Requirements: Go 1.22 or higher.

git clone https://github.com/kryvora-network/kryvora-node.git
cd kryvora-node
make build
./bin/kryvora-node --config config.yaml --token "your_token_here"

Configuration

Configuration is loaded from config.yaml or set via environment variables.

Key Type Default Description
node.id string auto-generated Unique identifier for worker node
node.listen_addr string 0.0.0.0:4177 Local address for telemetry and metrics
node.data_dir string /var/lib/kryvora Local state and task database directory
auth.bootstrap_token string "" Mandatory: Genesis Node Key activation token
hub.endpoint string https://hub.kryvora.network:4188 Upstream coordination hub address
hub.heartbeat_interval int 30 Interval in seconds between hub pings
telemetry.enabled bool true Expose Prometheus metrics on /metrics

Local Endpoints

When running, the daemon exposes the following endpoints on port 4177:

Example query:

curl -s http://127.0.0.1:4177/status

Security

Please report vulnerabilities directly to [email protected] rather than opening public issues.

License

Apache License 2.0. See LICENSE for details.

kryvora-node (kryvora-network/kryvora-node)

Searching Database…

1.4K ·GitHub
Kryvora-node
What is this?It's the official client daemon for Kryvora Network, a decentralized physical infrastructure network (DePIN). Running it turns your machine into a verification worker that connects to the Kryvora Hub, executes telemetry probes, verifies peer state, and reports proof of availability.
Is this something I install on my own hardware, or a hosted service?You install it on your own hardware: it runs as a Linux systemd service, a Docker Compose container, or a binary built from source. Once up, it stays connected to the coordination hub at hub.kryvora.network:4188.
How do I get a node running?Three options: run the automated install script on Linux (it registers a systemd service), use Docker Compose from the cloned repo, or build from source with Go 1.22+. Every path needs your bootstrap token in the config.
What do I need before the daemon will connect to the network?An active Genesis Node Key — a soulbound on-chain credential on Arbitrum One (contract 0xBCf2cD12D1D37578fA7C69805fE77788e866BE1a). Connect your wallet at node.kryvora.network to obtain the bootstrap token the hub requires.
Any gotchas that trip up new node runners?The hub rejects any node lacking a valid bootstrap token, so there's no anonymous operation. You also need 2 GB RAM minimum, 20 GB of SSD storage, and inbound port 4177 open for telemetry probes.
Does it run on Windows and Mac, or Linux servers only?Confirmed paths are Linux (systemd) and Docker; source builds target x86_64 and arm64. The README doesn't mention native Windows or macOS support.
How do I keep an eye on my node once it's running?The daemon serves three local endpoints on port 4177: /health for lifecycle status, /status for peer connectivity, block height and sync state, and /metrics with Prometheus-compatible counters, on by default.
How often does the node check in with the hub?Every 30 seconds by default, controlled by hub.heartbeat_interval in config.yaml or an environment variable; the hub endpoint address is configurable the same way.
Where does the node store its state?In the directory set by node.datadir, which defaults to /var/lib/kryvora, while the daemon listens locally on 0.0.0.0:4177. Both are overridable in config.yaml or via environment variables.
What are similar projects?kubo, gun, node, go-ethereum, signoz, quip-validator, thanos, canopy
Which topics is it in?telemetry, crypto, prometheus, decentralized, arm64, web3, infrastructure, blockchain, golang, distributed-systems, docker-compose, monitoring
Creator
kryvora-network
Size
1.4 MB
Stars
1.4K
Updated
CommitSep 20Releasev0.2.0Sep 22
Age
25d
Commits · 90 Days