Installation Guide¶

Get your Verdikta Arbiter Node up and running with our automated installer. This comprehensive guide walks you through every step, from prerequisites to final configuration.

🆕 What's New: Automated Fund Management & Multi-Provider Support¶

The installer now includes automatic Chainlink key funding, fund recovery, and multi-provider AI support:

Fund Management: - Zero Manual Transfers: Automatically fund your Chainlink keys during installation - Smart Recovery: Easily recover excess ETH and accumulated LINK tokens - Error-Proof Setup: Built-in validation and retry mechanisms - Post-Installation Tools: Manage oracle finances throughout the lifecycle

Multi-Provider AI Support: - Four AI Providers: OpenAI, Anthropic, Hyperbolic, and xAI - ClassID-Based Configuration: Choose which arbitration classes to support - Flexible API Key Setup: Configure only the providers you need - Local Model Support: ClassID 129 runs Ollama models locally (no API costs)

These features provide flexibility in cost management and model selection while simplifying the setup process!

Prerequisites¶

Before starting, ensure you have:

System Requirements¶

• OS: Ubuntu 20.04+, macOS 11+, or Windows WSL2
• Hardware: 8GB+ RAM, 200GB+ storage, 2+ CPU cores
• Software: Git, Docker, Node.js (auto-installed if missing)

Required API Keys¶

Note: The API keys you need depend on which ClassIDs you plan to support. See the ClassID Requirements section below for details.

AI Provider Keys (based on your ClassID choices): - OpenAI API Key: For GPT models (Get API Key) - Anthropic API Key: For Claude models (Get API Key) - Hyperbolic API Key: For cost-effective open-source models (Get API Key) - xAI API Key: For Grok models (Get API Key)

Infrastructure Keys (required for all installations): - Web3 Provider: Choose Infura, Alchemy, or QuickNode (Infura, Alchemy) - IPFS Service (Optional): For document storage (Pinata recommended)

ClassID Requirements¶

Your arbiter node can support different classes of arbitration requests, each requiring specific API keys:

Recommendations: - For testing/learning: Start with ClassID 129 (no API keys needed, uses local Ollama models) - For production: Use ClassID 128 or 131 depending on model diversity requirements - For cost optimization: Consider ClassID 130 (Hyperbolic provides cost-effective access to open-source models) - For maximum flexibility: Support ClassID 131 (requires all four AI provider keys)

Network Funds¶

For Testing: - Base Sepolia ETH (free from Base Sepolia Faucet) - Queries are paid for with Base Sepolia LINK (free from Chainlink Faucet)

For Production: - Base Mainnet ETH (~\(50-100 USD) - Queries are paid for with Base Mainnet LINK (Users can purchase on exchanges--querries cost ~\)1 of LINK)

Wallet Setup¶

• Create a separate test wallet (never use your main wallet!)
• Export the private key (remove 0x prefix)
• Fund with testnet tokens for safe testing

Preliminary Steps¶

Step A: Clone Repository¶

Clone the Verdikta Arbiter repository and navigate to the installer:

git clone https://github.com/verdikta/verdikta-arbiter.git
cd verdikta-arbiter/installer

Step B: Run the Automated Installer¶

Start the installation process:

./bin/install.sh

The installer will guide you through 10 main steps. Here's what happens in each step:

The 10 Main Installation Steps¶

Step 1: System Prerequisites Check¶

The installer first verifies your system meets all requirements.

What It Checks¶

• Operating System: Ubuntu 20.04+, macOS 11+, or WSL2
• Hardware: Minimum 8GB RAM, 200GB storage
• Software: Node.js, Docker, Git
• Network: Internet connectivity

If Prerequisites Fail¶

The installer will offer to install missing components automatically:

Would you like to install Node.js v20.18.0 using nvm? (y/n): y
Would you like to install Docker? (y/n): y

Response: Type y to install automatically, or n to skip (not recommended).

Step 2: Environment Setup¶

Configure your installation directory, network selection, and API keys.

Installation Directory¶

Prompt: Installation directory [~/verdikta-arbiter-node]:

What to do: - Press Enter for the default location - Or type a custom path like /opt/verdikta-arbiter

Network Selection¶

Prompt: Select deployment network:

1) Base Sepolia (Testnet) - Recommended for testing
2) Base Mainnet - Production (requires real ETH)

What to choose: - Option 1: Base Sepolia testnet (free, recommended for learning) - Option 2: Base Mainnet (production, requires real ETH, payments to node made in LINK)

API Keys Configuration¶

OpenAI API Key¶

Prompt: Enter your OpenAI API Key (leave blank to skip):

Required for: ClassID 128, 131

How to get it:

1. Go to OpenAI Platform
2. Sign up or log in
3. Navigate to API Keys → "+ Create new secret key"
4. Name it "Verdikta Arbiter" and copy the key

Example: sk-proj-1234567890abcdef...

Anthropic API Key¶

Prompt: Enter your Anthropic API Key (leave blank to skip):

Required for: ClassID 128, 131

How to get it:

1. Go to Anthropic Console
2. Sign up or log in
3. Navigate to API Keys → "Create Key"
4. Copy the key

Example: sk-ant-api03-...

Hyperbolic API Key¶

Prompt: Enter your Hyperbolic API Key (leave blank to skip):

Required for: ClassID 130, 131

How to get it:

1. Go to Hyperbolic
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key and copy it

Example: hb_...

xAI API Key¶

Prompt: Enter your xAI API Key (leave blank to skip):

Required for: ClassID 131

How to get it:

1. Go to xAI Console
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key and copy it

Example: xai-...

Infura API Key (Required)¶

Prompt: Enter your Infura API Key:

How to get it:

1. Go to Infura.io and sign up (free)

2. Create a new project → Select Ethereum

3. Copy the Project ID from your dashboard

Example: 1234567890abcdef1234567890abcdef

Pinata JWT (Optional)¶

Prompt: Enter your Pinata JWT (leave blank to skip):

How to get it:

1. Go to Pinata.cloud and sign up

2. API Keys → "New Key" → Give admin permissions

3. Copy the JWT token

Wallet Private Key (Required)¶

Prompt: Enter your wallet private key for contract deployment (without 0x prefix):

⚠️ CRITICAL SECURITY STEPS:

1. Create a NEW test wallet in MetaMask (never use your main wallet)

2. Get Network Funds:

3. Base Sepolia: Go to Base Sepolia Faucet for free ETH

4. Base Mainnet: Purchase ETH and transfer to your test wallet (~$50-100 recommended)

5. Export the private key:

6. MetaMask → Account menu (3 dots) → Account Details
7. Export Private Key → Enter MetaMask password
8. Remove the 0x prefix from the key

Format: Exactly 64 hexadecimal characters (no 0x)
Example: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Step 3: AI Node Installation¶

The installer downloads and sets up the AI arbitration service: - Configures with your API keys (OpenAI, Anthropic, Hyperbolic, xAI as provided) - Integrates ClassID model pools from verdikta/common library - Sets up AI model connections for all configured providers - Displays available ClassIDs and their model configurations - Duration: ~5 minutes

Step 4: External Adapter Installation¶

Sets up the blockchain-AI bridge service: - Configures communication endpoints - Sets up bridge for Chainlink integration - Duration: ~4 minutes

Step 5: Docker & PostgreSQL Setup¶

Installs Docker containers and database: - Sets up PostgreSQL database for Chainlink - Configures container networking

Prompt: Please enter the existing PostgreSQL password (leave blank to generate a new one):

What to do: Press Enter to auto-generate a secure password (recommended)

Step 6: Chainlink Node Setup¶

Downloads and configures Chainlink node: - Sets up blockchain connectivity with your Web3 provider - Generates node credentials

Prompt: Enter email for Chainlink node login [admin@example.com]:

What to do: - Press Enter for default email - Or enter your preferred email for the UI login

Step 7: Smart Contract Deployment¶

Deploy the oracle contracts to your selected blockchain network.

Automated Contract Deployment¶

The installer automatically handles the complete deployment process:

1. Retrieves Chainlink node addresses automatically using the key management system
2. Compiles the ArbiterOperator smart contract
3. Deploys it to your selected network using your private key
4. Authorizes all Chainlink keys to interact with the contract
5. Saves all contract addresses and key information

What You'll See¶

[7/9] Deploying Smart Contracts...
✓ Automatically retrieving Chainlink node addresses
✓ Found 2 Chainlink keys to authorize
✓ Compiling contracts
✓ Deploying to Base Sepolia
✓ Contract deployed at: 0x1234567890abcdef...
✓ Authorizing all keys with operator contract
✓ Smart Contract deployment completed

If Deployment Fails¶

Check these common issues: - Insufficient funds: Your node needs Base Sepolia ETH (Testnet) or Base ETH (Mainnet) - Invalid private key: Should be 64 characters without 0x prefix - Network connectivity: Ensure stable internet connection - RPC endpoint: Verify your Web3 provider is working

Step 8: Job Configuration¶

Configure the number of arbiters for your node with automatic key management.

Arbiter Count Selection¶

Prompt: How many arbiters would you like to configure? (1-10)

What to choose: - 1 arbiter: Simple setup, good for getting started - 2-4 arbiters: Balanced load distribution - 5-10 arbiters: Maximum throughput for high-demand scenarios

Automatic Key Management¶

The installer automatically:

1. Calculates required keys: Creates 1 key for every 2 arbiters
2. 1-2 arbiters → 1 key
3. 3-4 arbiters → 2 keys
4. 5-6 arbiters → 3 keys

5. etc.

6. Generates keys: Creates new Ethereum keys in your Chainlink node

7. Assigns jobs: Maps arbiters to keys following the pattern:

8. Arbiters 1-2 → Key 1
9. Arbiters 3-4 → Key 2

10. Arbiters 5-6 → Key 3

11. Authorizes keys: All keys are automatically authorized with your operator contract

Sample Output:

Creating jobs for 4 arbiters...
✓ Job 1 created successfully with ID: 12345678-1234-1234-1234-123456789012
✓ Job 2 created successfully with ID: 23456789-2345-2345-2345-234567890123
✓ Job 3 created successfully with ID: 34567890-3456-3456-3456-345678901234
✓ Job 4 created successfully with ID: 45678901-4567-4567-4567-456789012345

Step 9: Oracle Registration¶

Register your oracle with the Verdikta dispatcher network to receive arbitration requests.

Registration Process¶

Prompt: Register with dispatcher? (y/n):

What to choose: - y: Register to participate in live arbitration requests from the network - n: Skip for local testing and development only

Aggregator Address Configuration¶

If registering, you'll be prompted for:

Prompt: Enter aggregator address:

What to provide: The dispatcher contract address provided by the Verdikta team - Base Sepolia: 0xE75426Ed0491a8290fC55CAA71ab5e1d95F4BaF6 (example) - Base Mainnet: Contact Verdikta team for current address

Class IDs Configuration¶

Prompt: Enter class IDs (comma-separated or space-separated) [128]:

What to provide: Arbitration categories your oracle can handle

Available Class IDs:

Examples: - Single class: 128 (requires OpenAI + Anthropic keys) - Multiple classes: 128,129 (requires OpenAI + Anthropic keys, Ollama models) - All commercial: 128,130,131 (requires all four AI provider keys) - Open-source only: 129 (no API keys required)

Registration Verification¶

After registration, the installer will: 1. Submit registration to the dispatcher contract 2. Verify oracle capabilities with provided class IDs 3. Confirm network connectivity 4. Save registration details to configuration files

Step 10: Automatic Chainlink Key Funding (Optional)¶

NEW FEATURE: The installer now offers automatic funding of your Chainlink keys! This optional step eliminates the need for manual token transfers.

What This Step Does¶

The installer can automatically fund your Chainlink keys with the optimal amount of ETH for gas fees using funds from your deployment wallet.

The Funding Process¶

Prompt: Would you like to automatically fund your Chainlink keys now? (y/n):

What to choose: - y: Proceed with automatic funding (recommended) - n: Skip automatic funding and fund manually later

Funding Options¶

If you choose automatic funding, you'll see:

Funding options:
  1) Use recommended amount (0.005 Base Sepolia ETH per key)
  2) Specify custom amount
  3) Skip automatic funding

Choose option (1-3) [1]:

Recommended Amounts: - Base Sepolia: 0.005 ETH per key (~50 queries worth of gas) - Base Mainnet: 0.002 ETH per key (~50 queries worth of gas)

Safety Features¶

• Balance Verification: Checks your deployment wallet has sufficient funds
• Cost Calculation: Shows total cost including gas fees before proceeding
• Transaction Monitoring: Waits for blockchain confirmation
• Error Recovery: Provides retry options if funding fails

Example Output¶

============================================================
  Optional: Automatic Chainlink Key Funding
============================================================

Your Chainlink keys need native ETH to pay for gas fees.
Recommended funding: 0.005 Base Sepolia ETH per key

Funding Summary:
  Keys to fund: 2
  Amount per key: 0.005 Base Sepolia ETH
  Total funding: 0.010 Base Sepolia ETH
  Estimated gas cost: 0.000084 Base Sepolia ETH
  Total cost: 0.010084 Base Sepolia ETH

✓ Automatic funding completed successfully!
✓ Your Chainlink keys are now funded and ready for operation.

If Automatic Funding Fails¶

Common causes and solutions:

• Insufficient Balance: Add more ETH to your deployment wallet
• Network Issues: Retry when network is stable
• Gas Price Spike: Wait for lower gas prices or increase funding amount

Manual Funding Alternative¶

If you skip automatic funding or it fails, you can:

1. Use the standalone script:

   ~/verdikta-arbiter-node/fund-chainlink-keys.sh
   

2. Manual transfer (traditional method):

3. Get key addresses: cat ~/verdikta-arbiter-node/installer/.contracts
4. Send ETH to each address using your wallet

Recommended Funding Amounts¶

Installation Complete! 🎉¶

Upon successful completion, you'll see:

============================================================
    MULTI-ARBITER CONFIGURATION COMPLETED SUCCESSFULLY     
============================================================
Configuration Summary:
✓ Bridge created/updated: verdikta-ai
✓ Arbiters configured: [Your selected number]
✓ Jobs created: [Number of successful jobs]
✓ Keys configured: [Number of keys]
✓ Configuration files updated

Access your services:
- Chainlink Node UI: http://localhost:6688
- External Adapter: http://[your-ip]:8080
- AI Node: http://localhost:3000

Final Installation Summary¶

Upon successful completion, you'll see the final summary:

====================================================
  Verdikta Arbiter Node Installation Complete!
====================================================

Access your services at:
  - AI Node:         http://localhost:3000
  - External Adapter: http://localhost:8080  
  - Chainlink Node:   http://localhost:6688

Verify Everything is Working¶

1. Check Service Status¶

cd ~/verdikta-arbiter-node
./arbiter-status.sh

Expected output:

[AI Node] Running on port 3000 ✓
[External Adapter] Running on port 8080 ✓
[Chainlink Node] Running on port 6688 ✓
[PostgreSQL] Running on port 5432 ✓

2. Test AI Node Health¶

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}

3. Verify Chainlink Jobs (Multi-Arbiter)¶

1. Open http://localhost:6688

2. Log in with saved credentials

3. Go to Jobs → Verify all your arbiter jobs are Active

4. Look for jobs named "Verdikta AI Arbiter 1", "Verdikta AI Arbiter 2", etc.

5. Each job should show as Active with unique job IDs

6. Check Key Management → EVM Chain Accounts

7. Verify all generated keys are present and funded
8. Each key should have the correct fromAddress assignments

Important Files & Credentials¶

After installation, save these critical files:

Multi-Arbiter Contract Information¶

File: ~/verdikta-arbiter-node/installer/.contracts

# Network Configuration
DEPLOYMENT_NETWORK=base_sepolia
NETWORK_TYPE=testnet

# Contract Information  
OPERATOR_ADDR=0x1234...
NODE_ADDRESS=0x5678...

# Multi-Arbiter Job IDs
ARBITER_COUNT=4
JOB_ID_1=abcd1234-5678-90ef-ghij-klmnopqrstuv
JOB_ID_2=bcde2345-6789-01fe-ghij-klmnopqrstuv
JOB_ID_3=cdef3456-7890-12fe-ghij-klmnopqrstuv
JOB_ID_4=defa4567-8901-23fe-ghij-klmnopqrstuv

# Key Management
KEYS_LIST=key1:0xabc...|key2:0xdef...

Chainlink Credentials¶

File Network-Specific Location: - Testnet: ~/.chainlink-testnet/.api - Mainnet: ~/.chainlink-mainnet/.api

Contents:

admin@verdikta.local
[your-generated-password]

Multi-Arbiter Job Information¶

File: ~/verdikta-arbiter-node/chainlink-node/info/multi_arbiter_job_info.txt

Verdikta Multi-Arbiter Chainlink Node Configuration
==================================================

Configuration Date: [timestamp]
Number of Arbiters: 4
Jobs Created: 4

Bridge Configuration:
- Bridge Name: verdikta-ai
- Bridge URL: http://[your-ip]:8080/evaluate

Job Details:
Arbiter 1: Job ID abc..., Key 0x123...
Arbiter 2: Job ID def..., Key 0x123...
Arbiter 3: Job ID ghi..., Key 0x456...
Arbiter 4: Job ID jkl..., Key 0x456...

Management Commands¶

Control your arbiter node with these commands:

cd ~/verdikta-arbiter-node

# Start all services
./start-arbiter.sh

# Stop all services  
./stop-arbiter.sh

# Check status
./arbiter-status.sh

# Fund Chainlink keys (post-installation)
./fund-chainlink-keys.sh

# Recover funds from Chainlink keys
./recover-chainlink-funds.sh

Fund Management Commands¶

Funding Chainlink Keys¶

# Interactive funding with recommended amounts
./fund-chainlink-keys.sh

# Fund with custom amount
./fund-chainlink-keys.sh --amount 0.01

# Preview funding without executing
./fund-chainlink-keys.sh --dry-run

# Automated funding (no prompts)
./fund-chainlink-keys.sh --amount 0.005 --force

Recovering Funds from Keys¶

# Interactive recovery (choose what to recover)
./recover-chainlink-funds.sh

# Recover excess ETH only
./recover-chainlink-funds.sh --eth-only

# Recover accumulated LINK tokens only
./recover-chainlink-funds.sh --link-only

# Recover both ETH and LINK
./recover-chainlink-funds.sh --both

# Preview recovery without executing
./recover-chainlink-funds.sh --dry-run --both

Troubleshooting Quick Fixes¶

Common Installation Issues¶

# Find what's using the port
sudo lsof -i :6688

# Kill the process or use different port
sudo kill -9 [PID]

# Check key management logs
cd ~/verdikta-arbiter-node
docker logs chainlink

# Retry specific job creation
cd verdikta-arbiter/installer
bash bin/configure-node.sh

# Check which network directory exists
ls ~/.chainlink-*

# For testnet issues
ls ~/.chainlink-testnet/

# For mainnet issues  
ls ~/.chainlink-mainnet/

# Get free testnet ETH
# Visit: https://www.alchemy.com/faucets/base-sepolia

# Check your wallet balance
# Ensure you have ~$50-100 worth of ETH for setup

# Start Docker service
sudo systemctl start docker

# Retry installation
bash bin/install.sh

# Check deployment wallet balance
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["YOUR_WALLET","latest"],"id":1}' \
  https://base-sepolia.infura.io/v3/YOUR_INFURA_KEY

# Retry funding with custom amount
./fund-chainlink-keys.sh --amount 0.003

# Use dry run to check what would happen
./fund-chainlink-keys.sh --dry-run

# Check current key balances
./recover-chainlink-funds.sh --dry-run --both

# Recover specific asset type
./recover-chainlink-funds.sh --eth-only --dry-run

# Check Chainlink node status
curl http://localhost:6688/health

# Verify Chainlink container is running
docker ps | grep chainlink

# Check all key addresses and balances
cat ~/verdikta-arbiter-node/installer/.contracts | grep KEY_.*_ADDRESS

# Monitor specific key balance
# (Replace KEY_ADDRESS with actual key)
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["KEY_ADDRESS","latest"],"id":1}' \
  https://base-sepolia.infura.io/v3/YOUR_INFURA_KEY

# Force re-funding if needed
./fund-chainlink-keys.sh --force --amount 0.005

Next Steps & Scaling¶

🎯 Getting Started (New Users)¶

1. Test with 1 Arbiter: Understand the system basics
2. Submit Test Requests: Use the testing tools to validate functionality
3. Monitor Performance: Check logs and metrics
4. Scale Gradually: Add more arbiters as you gain confidence

📈 Scaling Your Multi-Arbiter Setup¶

Performance Considerations¶

• 1-2 Arbiters: Good for learning and light workloads
• 3-5 Arbiters: Balanced performance for medium workloads
• 6-10 Arbiters: High-performance setup for heavy workloads

Resource Planning¶

• RAM: Add ~1GB per additional arbiter
• Storage: Add ~20GB per additional arbiter
• CPU: Monitor utilization and scale accordingly

🛠️ Advanced Configuration¶

For advanced configurations, see: - Multi-Arbiter Design Guide - Management & Monitoring - Troubleshooting Guide

💡 Production Deployment Tips¶

1. Start on Testnet: Always test thoroughly before mainnet
2. Monitor Costs: Track gas fees and optimize if needed
3. Backup Critical Files: Regularly backup configuration and keys
4. Monitor Health: Set up alerts for service availability
5. Scale Incrementally: Add arbiters gradually based on demand

🎉 Congratulations! Your Verdikta Multi-Arbiter Node is now running with automated fund management! Welcome to the future of decentralized dispute resolution!

New Fund Management Features¶

Your installation now includes powerful fund management tools:

• Automatic Key Funding: Eliminates manual ETH transfers during setup
• Fund Recovery: Easily recover excess ETH and accumulated LINK tokens
• Balance Monitoring: Built-in tools to check and manage key finances
• Error Recovery: Robust handling of funding failures and network issues

Key Commands to Remember¶

cd ~/verdikta-arbiter-node

# Core operations
./start-arbiter.sh          # Start all services
./stop-arbiter.sh           # Stop all services  
./arbiter-status.sh         # Check status

# Fund management
./fund-chainlink-keys.sh    # Add ETH to keys
./recover-chainlink-funds.sh # Recover ETH and LINK from keys

ClassID Configuration Summary¶

Your installation has been configured with ClassID model pools. The ClassIDs you can support depend on which API keys you provided:

To check your model configuration:

cd ~/verdikta-arbiter-node/ai-node
npm run display-classid

To reconfigure models:

cd ~/verdikta-arbiter-node/ai-node
npm run integrate-classid

Getting Help¶

• Complete Troubleshooting: Troubleshooting Guide
• Fund Management Guide: ~/verdikta-arbiter-node/installer/util/README-funding.md
• Recovery Guide: ~/verdikta-arbiter-node/installer/util/README-fund-recovery.md
• GitHub Issues: Report problems or ask questions
• Discord: Get community help in real-time
• Email: Contact support for urgent issues