From b6cfd5eae14428b56713d0403bf6a9a591c5b391 Mon Sep 17 00:00:00 2001 From: Steve Degosserie <723552+stiiifff@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:44:06 +0100 Subject: [PATCH] =?UTF-8?q?chore:=20=E2=99=BB=EF=B8=8F=20=20Updated=20Data?= =?UTF-8?q?Haven=20nodes=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/datahaven-bootnode.md | 29 ++++++ docs/datahaven-fullnode.md | 31 ++++++- docs/datahaven-validator.md | 170 ++++++++++++++++++++++++++---------- 3 files changed, 182 insertions(+), 48 deletions(-) diff --git a/docs/datahaven-bootnode.md b/docs/datahaven-bootnode.md index 9890abb6..9d59cd56 100644 --- a/docs/datahaven-bootnode.md +++ b/docs/datahaven-bootnode.md @@ -17,6 +17,35 @@ A bootnode serves as an entry point for peer discovery in the DataHaven network. - Persistent storage for node key - Open network port (default: 30333) +## Hardware Requirements + +Bootnodes have moderate hardware requirements as they only handle peer discovery and do not participate in consensus. Network bandwidth and uptime are the primary concerns. + +### Minimum Specifications + +| Component | Requirement | +|-----------|-------------| +| **CPU** | 4 physical cores @ 2.0 GHz | +| **RAM** | 8 GB DDR4 | +| **Storage** | 100 GB NVMe SSD | +| **Network** | 500 Mbit/s symmetric | + +### Recommended Specifications + +| Component | Requirement | +|-----------|-------------| +| **CPU** | 8 physical cores @ 3.0 GHz (Intel Ice Lake+ or AMD Zen3+) | +| **RAM** | 16 GB DDR4 | +| **Storage** | 250 GB NVMe SSD | +| **Network** | 1 Gbit/s symmetric | + +### Important Considerations + +- **High availability**: Bootnodes should have excellent uptime as they are entry points for the network +- **Geographic distribution**: Deploy bootnodes in multiple regions for network resilience +- **Static IP**: Required for stable multiaddress that other nodes can reference +- **DDoS protection**: Consider DDoS mitigation as bootnodes are publicly known endpoints + ## Key Requirements ### Node Key diff --git a/docs/datahaven-fullnode.md b/docs/datahaven-fullnode.md index e4185104..9e07aac7 100644 --- a/docs/datahaven-fullnode.md +++ b/docs/datahaven-fullnode.md @@ -15,10 +15,39 @@ Full nodes synchronize with the DataHaven network and provide RPC endpoints for ## Prerequisites - DataHaven node binary or Docker image -- Sufficient storage for chain data (200+ GB recommended) +- Sufficient storage for chain data - Stable network connection - Open network ports (30333, optionally 9944) +## Hardware Requirements + +Full nodes have moderate hardware requirements as they sync the chain and serve RPC requests but do not participate in consensus. + +### Minimum Specifications + +| Component | Requirement | +|-----------|-------------| +| **CPU** | 4 physical cores @ 2.5 GHz | +| **RAM** | 16 GB DDR4 | +| **Storage** | 500 GB NVMe SSD | +| **Network** | 100 Mbit/s symmetric | + +### Recommended Specifications + +| Component | Requirement | +|-----------|-------------| +| **CPU** | 8 physical cores @ 3.0 GHz (Intel Ice Lake+ or AMD Zen3+) | +| **RAM** | 32 GB DDR4 | +| **Storage** | 1 TB NVMe SSD | +| **Network** | 500 Mbit/s symmetric | + +### Important Considerations + +- **Storage growth**: Plan for chain data growth over time; storage requirements will increase +- **RPC load**: If serving many RPC requests, consider higher CPU and RAM specifications +- **Archive node**: If running an archive node (full history), significantly more storage is required (2+ TB) +- **Cloud compatible**: Unlike validators, full nodes can run effectively on cloud VPS + ## Key Requirements ### No Session Keys Required diff --git a/docs/datahaven-validator.md b/docs/datahaven-validator.md index 932eade2..2ccace75 100644 --- a/docs/datahaven-validator.md +++ b/docs/datahaven-validator.md @@ -10,16 +10,46 @@ Validator nodes participate in consensus, produce blocks, and secure the DataHav - Sign GRANDPA finality votes - Submit ImOnline heartbeats - Participate in BEEFY bridge consensus -- Earn rewards for block production +- Earn rewards for block production and consensus participation ## Prerequisites - DataHaven node binary or Docker image -- Funded account with staking balance +- ECDSA keypair for operator registration on EigenLayer AVS - Persistent storage for chain data - Stable network connection - Open network ports (30333, optionally 9944) +## Hardware Requirements + +Validators have the highest hardware requirements as they participate in block production and consensus. Single-threaded CPU performance is critical. + +### Minimum Specifications + +| Component | Requirement | +|-----------|-------------| +| **CPU** | 8 physical cores @ 3.4 GHz (Intel Ice Lake+ or AMD Zen3+) | +| **RAM** | 32 GB DDR4 ECC | +| **Storage** | 1 TB NVMe SSD (low latency) | +| **Network** | 500 Mbit/s symmetric | + +### Recommended Specifications + +| Component | Requirement | +|-----------|-------------| +| **CPU** | Intel Xeon E-2386/E-2388 or AMD Ryzen 9 5950x/5900x | +| **RAM** | 64 GB DDR4 ECC | +| **Storage** | 2 TB NVMe SSD | +| **Network** | 1 Gbit/s symmetric | + +### Important Considerations + +- **Disable Hyper-Threading/SMT**: Single-threaded performance is prioritized over core count +- **Bare metal preferred**: Cloud VPS may have inconsistent performance due to shared resources +- **Dedicated server**: Do not run other applications on the validator machine +- **Docker not recommended**: Running in containers can significantly impact performance +- **Redundancy**: Consider primary and backup servers in different data centers + ## Key Requirements ### Session Keys (4 Required) @@ -100,17 +130,22 @@ The entrypoint script (`operator/scripts/docker-entrypoint.sh`) automatically in ## Wallet Requirements -### Controller Account +### Operator Account (ECDSA) -- **Purpose**: Controls validator operations -- **Required Balance**: Minimum staking amount + transaction fees -- **Funding**: Must be funded before validator registration +DataHaven validators are EigenLayer operators. The operator account is used to: +- Register as an operator on the DataHaven AVS (on Ethereum) +- Sign the `session.setKeys` extrinsic to associate session keys with the operator -### Generate Controller Account +**Important**: +- The account **does NOT need to be funded** on DataHaven - staking happens via EigenLayer delegation on Ethereum +- Token holders delegate stake to operators on EigenLayer, not on the DataHaven chain +- The same private key that controls the operator address on the AVS must sign the session keys transaction + +### Generate Operator Account (ECDSA) ```bash -# Generate new account -datahaven-node key generate +# Generate ECDSA keypair using datahaven-node +datahaven-node key generate --scheme ecdsa # Output: # Secret phrase: @@ -118,7 +153,21 @@ datahaven-node key generate # Secret seed: 0x... # Public key (hex): 0x... # Account ID: 0x... (20-byte Ethereum-style address) -# SS58 Address: ... + +# Derive Ethereum address from the hex public key using Foundry's cast +cast wallet address + +# This gives you the Ethereum address to register on the AVS +``` + +### Alternative: Generate with cast (Foundry) + +```bash +# Generate a new keypair +cast wallet new + +# Or import from private key +cast wallet address --private-key 0x... ``` ## CLI Flags @@ -157,13 +206,29 @@ datahaven-node \ ## Complete Setup Example -### 1. Generate Keys +### 1. Generate Operator Account (ECDSA) ```bash -# Generate controller account -SEED="your secure seed phrase here" -echo $SEED | datahaven-node key inspect +# Generate ECDSA keypair for operator registration +datahaven-node key generate --scheme ecdsa +# Save the seed phrase and note the public key hex +# Example output: +# Secret phrase: "word1 word2 ... word12" +# Public key (hex): 0x0123456789abcdef... + +# Get the Ethereum address for AVS registration +OPERATOR_ETH_ADDRESS=$(cast wallet address 0x) +echo "Operator ETH Address: $OPERATOR_ETH_ADDRESS" +``` + +### 2. Register as Operator on EigenLayer AVS + +Before setting session keys, register your operator address on the DataHaven AVS contract on Ethereum. See [On-Chain Registration](#on-chain-registration) for details. + +### 3. Generate Session Keys + +```bash # Start node to generate session keys via RPC datahaven-node \ --chain stagenet-local \ @@ -186,17 +251,7 @@ echo "Session Keys: $SESSION_KEYS" pkill -f datahaven-node ``` -### 2. Fund Controller Account - -```bash -# Get account address from seed -CONTROLLER_ADDR=$(echo $SEED | datahaven-node key inspect --output-type json | jq -r '.ss58PublicKey') - -# Fund account via faucet or transfer from another account -# Minimum: Staking amount + fees (e.g., 1000 HAVE + 10 HAVE fees) -``` - -### 3. Start Validator Node +### 4. Start Validator Node ```bash datahaven-node \ @@ -211,7 +266,7 @@ datahaven-node \ --log info ``` -### 4. Register Validator On-Chain +### 5. Set Session Keys On-Chain See [On-Chain Registration](#on-chain-registration) section below. @@ -314,7 +369,23 @@ spec: ## On-Chain Registration -### Step 1: Set Session Keys +### Step 1: Register as Operator on EigenLayer AVS + +Before setting session keys, you must register your operator address on the DataHaven AVS contract on Ethereum. This establishes your identity as a validator operator. + +```solidity +// DataHavenServiceManager.sol +function registerOperatorToAVS( + address operator, + ISignatureUtils.SignatureWithSaltAndExpiry memory operatorSignature +) external; +``` + +See `contracts/` directory and `test/scripts/` for registration scripts. + +### Step 2: Set Session Keys + +After registering on the AVS, submit your session keys to the DataHaven chain. **Important**: The transaction must be signed with the same private key used for AVS registration, so the session keys are associated with your operator address. Using Polkadot.js Apps or TypeScript: @@ -326,30 +397,18 @@ const api = await ApiPromise.create({ provider: new WsProvider('ws://localhost:9944') }); +// Use 'ethereum' keyring type for ECDSA keys const keyring = new Keyring({ type: 'ethereum' }); -const controller = keyring.addFromUri('your seed phrase'); +// Use the same seed phrase as your AVS operator account +const operator = keyring.addFromUri('your operator seed phrase'); // Set session keys (from author_rotateKeys RPC) const sessionKeys = '0x...'; // Combined public keys hex const setKeysTx = api.tx.session.setKeys(sessionKeys, []); -await setKeysTx.signAndSend(controller); +await setKeysTx.signAndSend(operator); ``` -### Step 2: Register with EigenLayer AVS - -Validators must register with the DataHaven AVS smart contract on Ethereum. - -```solidity -// DataHavenServiceManager.sol -function registerOperatorToAVS( - address operator, - ISignatureUtils.SignatureWithSaltAndExpiry memory operatorSignature -) external; -``` - -See `contracts/` directory and `test/scripts/` for registration scripts. - ### Step 3: Verify Registration ```bash @@ -423,10 +482,27 @@ curl -H "Content-Type: application/json" \ ### Issue: Not in Active Validator Set **Check:** -1. Sufficient stake amount -2. Not slashed -3. Session transition period -4. Maximum validator count not exceeded +1. Operator is registered on the DataHaven AVS contract (Ethereum) +2. Operator has sufficient delegated stake on EigenLayer +3. Session keys are correctly associated with operator address +4. Not slashed on EigenLayer +5. Session transition period (changes take effect in the next session) +6. Maximum validator count not exceeded + +### Issue: Session Keys Not Linked to Operator + +**Check:** +1. The `session.setKeys` transaction was signed with the same private key registered on the AVS +2. Verify the signing address matches your operator address on the AVS contract +3. Use `author_hasSessionKeys` RPC to confirm keys are stored locally + +**Solution:** +```bash +# Verify your operator address matches what's registered on AVS +cast wallet address + +# Re-submit session.setKeys with the correct operator account +``` ## Security Considerations