axionax Core v1.5 – Quick Start Guide

🎯 What You'll Learn

Start a local testnet environment
Run an axionax node
Become a validator
Register as a compute worker
Submit and monitor jobs

⚡ Quick Setup (5 minutes)

Step 1: Prerequisites

Docker Desktop installed and running
Go 1.21+ (for building from source)
16GB RAM available

Step 2: Clone and Build

# Clone repository
git clone https://github.com/axionaxprotocol/axionax-core.git
cd axionax-core
# Build axionax Core
make build

Step 3: Start Testnet

# Start local testnet (Anvil + Explorer + Faucet)
cd axionax_v1.5_Testnet_in_a_Box
docker compose up -d
# Verify services
docker compose ps

✅ hardhat (Anvil) - http://localhost:8545
✅ blockscout - http://localhost:4001
✅ faucet - http://localhost:8080

Step 4: Configure axionax Node

cd ..
./build/axionax-core config init

Edit config.yaml to connect to local testnet (already configured by default).

Step 5: Start Your Node

./build/axionax-core start --network testnet

🎉 Success! Your axionax node is now running!

👤 User Paths

Choose your path:

Path A: 🏛️ Run a Validator

Minimum 10,000 AXX stake
Reliable uptime
Fast verification capabilities

Generate keys:

./build/axionax-core keys generate --type validator

Get testnet AXX:

curl -H "Authorization: Basic YWRtaW46cGFzc3dvcmQ=" "http://localhost:8081/request?address=0xYourValidatorAddress"
# Or visit http://localhost:8080 in browser

Stake AXX:

./build/axionax-core stake deposit 10000 --address 0xYourValidatorAddress

Start validating:
```
./build/axionax-core validator start
```
Check status:
```
./build/axionax-core validator status
```

# Expected output:
📊 Validator Status:
  Status: Active
  Stake: 10,000 AXX
  Validations: 0
  Success Rate: N/A (new validator)

Path B: 🔧 Run a Worker

Capable hardware (GPU recommended)
Stable internet connection
Minimum stake for registration

Create hardware spec:

cat > worker-specs.json <<EOF
{
  "gpus": [{
    "model": "NVIDIA RTX 4090",
    "vram": 24,
    "count": 1
  }],
  "cpu_cores": 16,
  "ram": 64,
  "storage": 1000,
  "bandwidth": 1000,
  "region": "us-west",
  "asn": "AS15169",
  "organization": "my-org"
}
EOF

Generate worker keys:

./build/axionax-core keys generate --type worker

Get testnet AXX from faucet (same as validator)

Register as worker:

./build/axionax-core worker register --specs worker-specs.json

Start worker:
```
./build/axionax-core worker start
```
Monitor status:
```
./build/axionax-core worker status
```

# Expected output:
📊 Worker Status:
  Status: Active
  Jobs Completed: 0
  Success Rate: N/A (new worker)
  Current Quota: 0%

Path C: 💼 Submit Jobs (Client)

Create job specification:

{
  "specs": {
    "gpu": "NVIDIA RTX 4090",
    "vram": 24,
    "framework": "PyTorch",
    "region": "us-west"
  },
  "sla": {
    "max_latency": "30s",
    "max_retries": 3,
    "timeout": "300s",
    "required_uptime": 0.99
  }
}

Submit via RPC:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "axn_submitJob",
    "params": [/* job spec here */],
    "id": 1
  }'

Monitor job:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "axn_getJobStatus",
    "params": ["job_abc123"],
    "id": 1
  }'

🔍 Monitoring & Debugging

View Logs

# Node logs
tail -f ~/.axionax/logs/node.log
# Docker logs
cd axionax_v1.5_Testnet_in_a_Box
docker compose logs -f hardhat

Check Metrics

Visit http://localhost:9090/metrics for Prometheus metrics.

Explore Blockchain

Visit http://localhost:4001 for Blockscout explorer.

Query Pricing

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"axn_getPricingInfo","params":[],"id":1}'

🛠️ Common Commands

Configuration

# Show current config
./build/axionax-core config show
# Initialize default config
./build/axionax-core config init

Keys Management

# Generate new key
./build/axionax-core keys generate --type validator
# List keys
./build/axionax-core keys list

Staking

# Check balance
./build/axionax-core stake balance
# Deposit stake
./build/axionax-core stake deposit 10000 --address 0x...
# Withdraw stake
./build/axionax-core stake withdraw 5000

Status Checks

# Node version
./build/axionax-core version
# Validator status
./build/axionax-core validator status
# Worker status
./build/axionax-core worker status

🐛 Troubleshooting

Connection Refused

Problem: Cannot connect to RPC endpoint

# Check if testnet is running
cd axionax_v1.5_Testnet_in_a_Box
docker compose ps
# Restart if needed
docker compose restart

Chain ID Mismatch

Problem: Wrong chain ID

Solution: Check config.yaml has chain_id: 31337

Insufficient Funds

Problem: Not enough AXX for transactions

Solution: Request from faucet:

curl -H "Authorization: Basic YWRtaW46cGFzc3dvcmQ=" \
  "http://localhost:8081/request?address=0xYourAddress"

Docker Issues

Problem: Docker containers not starting

# Clean up
docker compose down -v
# Restart
docker compose up -d

📚 Next Steps

🆘 Getting Help

⚠️ Testnet Disclaimer

This is a testnet environment. Do not use real assets or run this in production without proper security audits.