Node Setup - Arcium Docs

Overview

As a node operator, you’ll set up your own Arx node to participate in the Arcium network. This guide walks you through each step of the process. First, you’ll prepare your environment by installing the necessary tools and generating security keys. Then, you’ll get your node registered onchain and configure it to run. Finally, you’ll connect to other nodes in a cluster and start doing computations. By the end, you will:

Install the Arcium tooling
Generate required keypairs
Fund accounts with SOL
Initialize onchain node accounts
Configure your node
Join or create a cluster
Deploy your node with Docker

Prerequisites

Before starting, ensure you have the following installed:

Rust: Install from rustup.rs
Solana CLI 2.3.0: Install from Solana’s documentation
Docker & Docker Compose: Install from Docker’s documentation
OpenSSL: Install from OpenSSL’s documentation (usually pre-installed on macOS/Linux)
Git: For cloning repositories and version control

You’ll also need:

A reliable internet connection
Basic familiarity with command-line tools

Recommended System Requirements:

Resource	Recommendation
RAM	32GB+
CPU	12+ cores, 2.8GHz+ base
Bandwidth	1 Gbit/s minimum
Disk	Minimal (node is not disk-intensive)
GPU	Not required

Network Requirements - Open these ports:

Port	Protocol	Purpose
8001	TCP & UDP	MPC protocol communication
8002	TCP & UDP	BLS signature aggregation
8012	TCP & UDP	TD preprocessing
8013	TCP & UDP	TD registration
9091	TCP & UDP	Prometheus metrics

Windows Users: Arcium doesn’t run natively on Windows yet. Use Windows Subsystem for Linux (WSL2) with Ubuntu to follow this guide.

Step 1: Set Up Your Workspace

Create a dedicated folder for your node setup to keep everything organized:

mkdir arcium-node-setup
cd arcium-node-setup

Stay in this directory for all remaining steps. All file paths and Docker commands assume you’re working from arcium-node-setup/.

You’ll also need to know your public IP address for the next steps. Here’s a quick way to find it:

curl https://ipecho.net/plain ; echo

Step 2: Install Arcium Tooling

The Arcium tooling suite includes the CLI and Arx node software. Install it using the automated installer:

curl --proto '=https' --tlsv1.2 -sSfL https://install.arcium.com/ | bash

This script will:

Check for all required dependencies
Install arcup (Arcium’s version manager)
Install the latest Arcium CLI
Install the Arx node software

Verify the installation:

arcium --version && arcup --version

If you prefer manual installation, see the installation guide for detailed instructions.

Step 3: Generate Required Keypairs

Your Arx node needs five different keypairs for secure operation. Create these in your arcium-node-setup directory:

3.1 Node Authority Keypair

This Solana keypair identifies your node and handles onchain operations:

solana-keygen new --outfile node-keypair.json --no-bip39-passphrase

The --no-bip39-passphrase flag creates a keypair without a passphrase for easier automation.

3.2 Callback Authority Keypair

This Solana keypair signs callback computations and must be different from your node keypair for security separation:

solana-keygen new --outfile callback-kp.json --no-bip39-passphrase

3.3 Identity Keypair

This keypair handles node-to-node communication and must be in PKCS#8 format:

openssl genpkey -algorithm Ed25519 -out identity.pem

3.4 BLS Keypair

This keypair is used for BLS (Boneh-Lynn-Shacham) threshold signatures on MPC computation callbacks. Generate it using the Arcium CLI:

arcium gen-bls-key bls-keypair.json

This creates a 32-byte private key stored as a JSON array format.

3.5 X25519 Keypair

This keypair is used for encrypted communication between nodes:

arcium generate-x25519 -o x25519-keypair.json

This creates a 32-byte X25519 private key stored in JSON array format.

Keep these keypairs safe and private. Back them up to a secure location outside your VPS - you’ll need them to restore your node if something goes wrong. Never share them with anyone.

Step 4: Fund Your Accounts

Your node and callback accounts need SOL for transaction fees. Transfer SOL to both accounts and verify balances:

# Check your account addresses
solana address --keypair node-keypair.json
solana address --keypair callback-kp.json

# Verify balances
solana balance "$(solana address --keypair node-keypair.json)"
solana balance "$(solana address --keypair callback-kp.json)"

On devnet, you can use solana airdrop 2 <address> -u devnet or the web faucet to get free SOL for testing.

On mainnet, SOL has real economic value. Ensure you have sufficient funds before proceeding.

Step 5: Initialize Node Accounts

Now we’ll register your node with the Arcium network by creating its onchain accounts. This step tells the blockchain about your node and its capabilities.

Set your Solana CLI to the target network once so you can avoid passing --rpc-url <rpc-url> repeatedly: solana config set --url https://api.mainnet-beta.solana.com (or https://api.devnet.solana.com for devnet)

For guidance on choosing a reliable endpoint, see the RPC Provider Recommendations. Use the init-arx-accs command to initialize all required onchain accounts for your node:

arcium init-arx-accs \
  --keypair-path node-keypair.json \
  --callback-keypair-path callback-kp.json \
  --peer-keypair-path identity.pem \
  --bls-keypair-path bls-keypair.json \
  --x25519-keypair-path x25519-keypair.json \
  --node-offset <your-node-offset> \
  --ip-address <your-public-ip> \
  --rpc-url <your-rpc-url>

Required Parameters:

--keypair-path: Path to your node authority keypair
--callback-keypair-path: Path to your callback authority keypair
--peer-keypair-path: Path to your identity keypair (PEM format)
--bls-keypair-path: Path to your BLS keypair (JSON array format)
--x25519-keypair-path: Path to your X25519 keypair (JSON array format)
--node-offset: Your node’s unique ID number on the network. Choose any unique number. If you get an error during setup saying your number is already taken, just pick a different one and try again.
--ip-address: Your node’s public IP address
--rpc-url: Solana RPC endpoint (mainnet or devnet)

If successful, you’ll see confirmation that your node accounts have been initialized onchain.

Step 6: Configure Your Node

The configuration file specifies which network to connect to, how to communicate with other nodes, and various operational settings. Create a node-config.toml file in your arcium-node-setup directory:

[node]
offset = <your-node-offset>  # Your node offset from step 5

[solana]
endpoint_rpc = "<your-rpc-provider-url-here>"  # e.g., https://api.mainnet-beta.solana.com or https://api.devnet.solana.com
endpoint_wss = "<your-rpc-websocket-url-here>"   # Replace with your RPC provider WebSocket URL (e.g., wss://api.mainnet-beta.solana.com)

Upgrading from v0.7.0? The [network] section, cluster, commitment, hardware_claim, starting_epoch, and ending_epoch fields have been removed. Update your node-config.toml to the simplified format above.

Step 7: Cluster Operations

Clusters are groups of nodes that collaborate on MPC computations. For background on cluster concepts, see Clusters Overview. Most operators should join an existing cluster. Only create your own cluster if you’re coordinating a group of nodes.

Join Existing Cluster
Create New Cluster

To join an existing cluster, you must first be proposed by the cluster authority. Once proposed, accept the invitation:

arcium join-cluster true \
  --keypair-path node-keypair.json \
  --node-offset <your-node-offset> \
  --cluster-offset <cluster-offset> \
  --rpc-url <your-rpc-url>

Parameters:

true: Accept the join request (use false to reject)
--node-offset: Your node’s unique identifier (chosen during node initialization)
--cluster-offset: The cluster’s unique identifier (different from node offset - clusters and nodes have separate ID spaces)

You cannot join a cluster unless the cluster owner has first proposed you using propose-join-cluster.

If you want to create a new cluster and invite other nodes:1. Create the Cluster

arcium init-cluster \
  --keypair-path node-keypair.json \
  --offset <cluster-offset> \
  --max-nodes <max-nodes> \
  --rpc-url <your-rpc-url>

Parameters:

--offset: Unique identifier for your cluster (different from your node offset)
--max-nodes: Maximum number of nodes in the cluster

Optional Parameters:

--mempool-size: Size of the mempool (Tiny, Small, Medium, Large). Defaults to Tiny
--price-per-cu: Initial price per compute unit in lamports. Defaults to 1
--propose-node: Automatically propose a node to join after creation

2. Propose Nodes to JoinAfter creating the cluster, you must propose each node that should join. Nodes cannot join without being proposed first:

arcium propose-join-cluster \
  --keypair-path node-keypair.json \
  --cluster-offset <cluster-offset> \
  --node-offset <node-to-propose-offset> \
  --rpc-url <your-rpc-url>

Parameters:

--cluster-offset: Your cluster’s offset
--node-offset: The offset of the node you’re inviting

You can also propose a node inline when creating the cluster using --propose-node <node-offset>

3. Wait for Nodes to AcceptOnce proposed, each node must accept the invitation using join-cluster true (see Join tab).

Submit Aggregated BLS Key (Required After Cluster is Full)

The command will verify that all cluster slots are filled before submitting. If nodes are still pending, it will fail with an error.

Once all nodes have joined the cluster, all nodes must aggregate and submit the combined BLS public key. This enables threshold BLS signatures for computation callbacks:

arcium submit-aggregated-bls-key \
  --keypair-path node-keypair.json \
  --cluster-offset <cluster-offset> \
  --node-offset <your-node-offset> \
  --rpc-url <your-rpc-url>

Parameters:

--keypair-path: Your node authority keypair (must be a node in the cluster)
--cluster-offset: The cluster’s offset
--node-offset: Your node’s offset within the cluster

All nodes need to run this command. The CLI will automatically fetch all node BLS public keys from the cluster and aggregate them.

Activate the Cluster (Cluster Authority Only)

After all nodes have submitted the aggregated BLS key, the cluster authority must activate the cluster:

arcium activate-cluster \
  --keypair-path <cluster-authority-keypair> \
  --cluster-offset <cluster-offset> \
  --rpc-url https://api.devnet.solana.com

Parameters:

--keypair-path: A keypair that has authority over the cluster
--cluster-offset: The cluster’s offset

Only the cluster authority can run this command. The cluster must have all BLS keys submitted before activation will succeed.

Step 8: Deploy Your Node

Before running Docker, prepare your environment and verify you have all required files:

mkdir -p arx-node-logs private-shares public-inputs
ls node-keypair.json callback-kp.json identity.pem bls-keypair.json x25519-keypair.json node-config.toml

Create a docker-compose.yml file in your arcium-node-setup directory:

services:
  arx-node:
    image: arcium/arx-node:v0.8.5
    container_name: arx-node
    restart: unless-stopped
    environment:
      NODE_IDENTITY_FILE: /usr/arx-node/node-keys/node_identity.pem
      NODE_KEYPAIR_FILE: /usr/arx-node/node-keys/node_keypair.json
      CALLBACK_AUTHORITY_KEYPAIR_FILE: /usr/arx-node/node-keys/callback_authority_keypair.json
      BLS_PRIVATE_KEY_FILE: /usr/arx-node/node-keys/bls_keypair.json
      X25519_PRIVATE_KEY_FILE: /usr/arx-node/node-keys/x25519_keypair.json
      ARX_METRICS_HOST: 0.0.0.0
      ARX_METRICS_PORT: 9091
    volumes:
      - ./node-config.toml:/usr/arx-node/arx/node_config.toml
      - ./node-keypair.json:/usr/arx-node/node-keys/node_keypair.json:ro
      - ./callback-kp.json:/usr/arx-node/node-keys/callback_authority_keypair.json:ro
      - ./identity.pem:/usr/arx-node/node-keys/node_identity.pem:ro
      - ./bls-keypair.json:/usr/arx-node/node-keys/bls_keypair.json:ro
      - ./x25519-keypair.json:/usr/arx-node/node-keys/x25519_keypair.json:ro
      - ./arx-node-logs:/usr/arx-node/logs
      - ./private-shares:/usr/arx-node/private-shares
      - ./public-inputs:/usr/arx-node/public-inputs
    ports:
      - "8001:8001/tcp"
      - "8001:8001/udp"
      - "8002:8002/tcp"
      - "8002:8002/udp"
      - "8012:8012/tcp"
      - "8012:8012/udp"
      - "8013:8013/tcp"
      - "8013:8013/udp"
      - "9091:9091/tcp"
      - "9091:9091/udp"

Key configuration:

image: arcium/arx-node:v0.8.5 — pinned version for stability
restart: unless-stopped — auto-restarts on crashes or server reboot
Volume mounts with :ro — read-only access for keypair files

Start the node:

docker compose up -d
docker compose ps
docker compose logs -f arx-node

Ensure ports 8001, 8002, 8012, 8013, 9091 (TCP & UDP) are open in your OS and cloud provider firewalls. The metrics endpoint (9091) has no authentication - restrict access to trusted networks only.

Alternative: docker run command

If you prefer using docker run directly:

docker run -d \
  --name arx-node \
  -e NODE_IDENTITY_FILE=/usr/arx-node/node-keys/node_identity.pem \
  -e NODE_KEYPAIR_FILE=/usr/arx-node/node-keys/node_keypair.json \
  -e CALLBACK_AUTHORITY_KEYPAIR_FILE=/usr/arx-node/node-keys/callback_authority_keypair.json \
  -e BLS_PRIVATE_KEY_FILE=/usr/arx-node/node-keys/bls_keypair.json \
  -e X25519_PRIVATE_KEY_FILE=/usr/arx-node/node-keys/x25519_keypair.json \
  -e ARX_METRICS_HOST=0.0.0.0 \
  -e ARX_METRICS_PORT=9091 \
  -v "$(pwd)/node-config.toml:/usr/arx-node/arx/node_config.toml" \
  -v "$(pwd)/node-keypair.json:/usr/arx-node/node-keys/node_keypair.json:ro" \
  -v "$(pwd)/callback-kp.json:/usr/arx-node/node-keys/callback_authority_keypair.json:ro" \
  -v "$(pwd)/identity.pem:/usr/arx-node/node-keys/node_identity.pem:ro" \
  -v "$(pwd)/bls-keypair.json:/usr/arx-node/node-keys/bls_keypair.json:ro" \
  -v "$(pwd)/x25519-keypair.json:/usr/arx-node/node-keys/x25519_keypair.json:ro" \
  -v "$(pwd)/arx-node-logs:/usr/arx-node/logs" \
  -v "$(pwd)/private-shares:/usr/arx-node/private-shares" \
  -v "$(pwd)/public-inputs:/usr/arx-node/public-inputs" \
  -p 8001:8001/tcp -p 8001:8001/udp \
  -p 8002:8002/tcp -p 8002:8002/udp \
  -p 8012:8012/tcp -p 8012:8012/udp \
  -p 8013:8013/tcp -p 8013:8013/udp \
  -p 9091:9091/tcp -p 9091:9091/udp \
  arcium/arx-node:v0.8.5

Step 9: Verify Node Operation

Check that your node is running correctly:

Check Node Status

arcium arx-info <your-node-offset> --rpc-url <your-rpc-url>

Check if Node is Active

arcium arx-active <your-node-offset> --rpc-url <your-rpc-url>

Metrics & Health

The node exposes Prometheus-compatible metrics on port 9091:

Endpoint	Description
`GET /metrics`	Prometheus-format metrics
`GET /health`	Health check (returns “OK”)

Verify:

curl -s http://localhost:9091/metrics | grep arx_
curl -s http://localhost:9091/health

Scrape with Prometheus and visualize with Grafana:

# prometheus.yml snippet
scrape_configs:
  - job_name: 'arx-node'
    static_configs:
      - targets: ['localhost:9091']

Monitor Logs

docker compose logs -f arx-node

Extract Internal Logs

If you need detailed logs for debugging:

docker cp arx-node:/usr/arx-node/logs ./node-logs
ls ./node-logs/  # Shows arx_log_<datetime>_<offset>.log

RPC Provider Recommendations

For better reliability, consider using dedicated RPC providers instead of the default public endpoints. Recommended providers:

Troubleshooting

Node fails with 'missing environment variable'

All 5 environment variables are required. Verify your docker-compose.yml includes:

NODE_KEYPAIR_FILE
CALLBACK_AUTHORITY_KEYPAIR_FILE
NODE_IDENTITY_FILE
BLS_PRIVATE_KEY_FILE
X25519_PRIVATE_KEY_FILE

Node fails with 'X25519 key invalid'

Regenerate the X25519 keypair:

arcium generate-x25519 -o x25519-keypair.json

Node Not Starting

Verify all 5 keypair files exist and are readable
Check that node-config.toml is valid TOML with all required fields
Ensure your IP address is accessible from the internet

Node can't reach peers

Verify firewall allows inbound on ports 8001, 8002, 8012, 8013, 9091 (TCP & UDP)
Check RPC endpoint is responsive
Verify node is active: arcium arx-active <offset>

Account Initialization Failed

Verify you have sufficient SOL for transaction fees
Check that your RPC endpoint is working
Ensure node offset is unique (try a different number)

Cannot Join Cluster

Verify you’ve been invited by the cluster authority
Check that cluster has available slots
Ensure your node is properly initialized

BLS aggregation failing

All cluster nodes need valid BLS keys. After all nodes join:

arcium submit-aggregated-bls-key \
  --keypair-path node-keypair.json \
  --cluster-offset <cluster-offset> \
  --node-offset <your-node-offset> \
  --rpc-url <your-rpc-url>

Callback authority out of funds

Check the balance and top up your callback account:

solana balance "$(solana address -k callback-kp.json)"
# On devnet:
solana airdrop 2 "$(solana address -k callback-kp.json)" -u devnet
# On mainnet: transfer SOL from your funded wallet

Docker Issues

Verify Docker is running
Check file permissions on mounted volumes
Ensure ports 8001, 8002, 8012, 8013, 9091 (TCP & UDP) are not already in use

Need more help? Join the Arcium Discord for community support, or review the installation troubleshooting guide.

What’s Next

Once your node is running successfully:

Join the Community: Connect with other node operators on Discord
Stay Updated: Keep your Arcium tooling updated with arcup install
Learn More: Read the Arcium Network Overview or Installation Guide

​Overview

​Prerequisites

​Step 1: Set Up Your Workspace

​Step 2: Install Arcium Tooling

​Step 3: Generate Required Keypairs

​3.1 Node Authority Keypair

​3.2 Callback Authority Keypair

​3.3 Identity Keypair

​3.4 BLS Keypair

​3.5 X25519 Keypair

​Step 4: Fund Your Accounts

​Step 5: Initialize Node Accounts

​Required Parameters:

​Step 6: Configure Your Node

​Step 7: Cluster Operations

​Submit Aggregated BLS Key (Required After Cluster is Full)

​Activate the Cluster (Cluster Authority Only)

​Step 8: Deploy Your Node

​Step 9: Verify Node Operation

​Check Node Status

​Check if Node is Active

​Metrics & Health

​Monitor Logs

​Extract Internal Logs

​RPC Provider Recommendations

​Troubleshooting

​What’s Next

Overview

Prerequisites

Step 1: Set Up Your Workspace

Step 2: Install Arcium Tooling

Step 3: Generate Required Keypairs

3.1 Node Authority Keypair

3.2 Callback Authority Keypair

3.3 Identity Keypair

3.4 BLS Keypair

3.5 X25519 Keypair

Step 4: Fund Your Accounts

Step 5: Initialize Node Accounts

Required Parameters:

Step 6: Configure Your Node

Step 7: Cluster Operations

Submit Aggregated BLS Key (Required After Cluster is Full)

Activate the Cluster (Cluster Authority Only)

Step 8: Deploy Your Node

Step 9: Verify Node Operation

Check Node Status

Check if Node is Active

Metrics & Health

Monitor Logs

Extract Internal Logs

RPC Provider Recommendations

Troubleshooting

What’s Next