jzero-node

This repository contains a Docker Compose configuration and genesis/config files for running a jzero testnet node. The project runs an execution-layer client (reth) and a consensus-layer client (Lighthouse) and includes configuration for a local/private network (chain ID 209).

NOTE: This repo contains example secrets (JWT token) and config files for testnets. Do not use these as-is for production or public nodes. Treat the config/metadata/jwtsecret and jwt.hex files as sensitive.

---

Quick overview ✅

• Execution client: ghcr.io/paradigmxyz/reth (configured in docker-compose.yaml)
• Consensus client: sigp/lighthouse (configured in docker-compose.yaml)
• Bootnode, genesis and testnet configuration: config/metadata/*
• Data directories: data/execution-data and data/consensus-data

---

Prerequisites 💡

• Docker and docker-compose installed
• Unix-like shell (examples use macOS fish style compatible commands)
• Sufficient disk space for blockchain data (the data/ tree is used by the containers)

---

Setup and Run (Quick Start) 🔧

1. Make a copy of the repository and move into the workspace:

git clone [email protected]:jfinchain/jzero.git
cd jzero-node

2. Update environment variables in .env (or copy a sample .env):

• NODE_PUBLIC_IP — your node's public IP address
• FEE_RECIPIENT — recommended fee recipient address for validators
• EL_BOOTNODE / CL_BOOTNODE — Bootnodes for execution/consensus layers

Tip: You can run the update_ip.sh script to set NODE_PUBLIC_IP automatically.

3. JWT secret: The Execution-Consensus API requires a JWT secret to authenticate. This repository used to contain config/metadata/jwtsecret and config/metadata/jwt.hex, but they have been removed from the working tree and replaced with jwtsecret.example.

Create a random 32-byte secret and save it into config/metadata/jwtsecret (and optionally jwt.hex with a 0x prefix):

Using openssl:

openssl rand -hex 32 > config/metadata/jwtsecret
printf "0x$(cat config/metadata/jwtsecret)" > config/metadata/jwt.hex

Or using Python:

python3 - << 'PY'
import os, binascii
secret = binascii.hexlify(os.urandom(32)).decode()
with open('config/metadata/jwtsecret','w') as f: f.write(secret)
with open('config/metadata/jwt.hex','w') as f: f.write('0x' + secret)
PY

4. Ensure you have your genesis config and config.yaml in config/metadata (this repo already includes a genesis.json and config.yaml).

5. Start the node services:

docker-compose up -d

6. Check logs:

docker-compose logs -f reth
docker-compose logs -f beacon

7. Stop the node:

docker-compose down

---

Configuration Files 🔎

• docker-compose.yaml — Defines the two services: reth (execution) and beacon (Lighthouse consensus). See service commands to understand ports and mount points.
• config/metadata/genesis.json — The testnet genesis for the network (Chain ID 209). Includes pre-allocations for addresses and fork schedule.
• config/metadata/config.yaml — Defines chain parameters and other ETH2 configurations.
• config/metadata/jwtsecret and jwt.hex — JWT secret used for authenticated RPC between reth and Lighthouse.
• config/metadata/bootstrap_nodes.txt — Consensus bootnodes to connect to the network.

---

Notes & Security ⚠️

• The repo currently contains jwtsecret in config/metadata, which is a secret. Rotate the secret if you are running this in a public or production-facing environment.
• Do not expose the JWT secret or private validator keys in public repositories.
• The Chain ID is set to 209. Double-check any external RPC or tools that expect mainnet or different chain IDs.
• The containers expose RPC ports (8545, 8546, 5052) to the host — be cautious about exposing them to the public internet without proper access control.

---

Validator & Deposits (High-level) 🏛️

• This project contains a deposit contract address in config/metadata/deposit_contract.txt. To run validators you will need to run a validator client and perform deposits if you intend to generate/participate validators on this network.
• The beacon service in docker-compose.yaml already starts Lighthouse beacon node with --validator-monitor-auto enabled. To run validators, place validator keys in the appropriate location (or run detached validator clients) and follow Lighthouse validator key generation/import instructions.

---

Contributing 🤝

• If you want to add improvements, or fix a bug, create a PR with a clear description and sample configurations.
• Add a LICENSE and CODE_OF_CONDUCT if you intend to make the project public.

---

Troubleshooting & Tips 🔍

• Logs and data reside in ./data/ — if you want to start fresh, stop services and remove ./data and let containers reinitialize.
• If you have NAT or firewall issues, ensure ports 30303 (execution, p2p), 9000 (consensus p2p, configured by default), 5052 (consensus HTTP) and 8545/8546 (execution HTTP/WebSocket) are correctly opened on your firewall.

---

License

No explicit license found — please add an appropriate license file (e.g., LICENSE, MIT, Apache 2.0) if this repository is to be shared publicly.

---

Thai summary (ภาษาไทย) 🇹🇭

สรุป: โปรเจ็กต์นี้คือชุดไฟล์ config และ docker-compose สำหรับรัน jzero testnet node โดยใช้ reth (execution) และ lighthouse (consensus).

ขั้นตอนด่วน:

1. ติดตั้ง Docker และ docker-compose
2. แก้ไข .env และสร้าง config/metadata/jwtsecret
3. รัน docker-compose up -d

หมายเหตุ: ไฟล์ jwtsecret อยู่ใน repo เป็นตัวอย่างเท่านั้น กรุณาสร้าง secret ใหม่และอย่าเผยแพร่สู่สาธารณะ

---

We removed the committed jwtsecret and jwt.hex files; please rotate any exposed keys if they were used, and do not add production secrets to source control. Use the included config/metadata/jwtsecret.example as a template. If you need to remove them from git history entirely, see the scripts/remove-jwt-secrets.sh script for safe commands to rewrite history.

Commands to remove from the working tree and push:

# Remove the files and make a commit
git rm --cached config/metadata/jwtsecret config/metadata/jwt.hex || true
git commit -m "chore: remove jwt secret files from repo"
git push origin HEAD

If the secrets were already pushed to any remote, follow the instructions above (BFG / git-filter-repo) to erase them from history and then force-push.