Setup a Testnet Node

Overview

Public Testnet on Solana Devnet for stress testing. Real computations; no economic value.

As a testnet 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 Devnet SOL

  • Initialize onchain node accounts

  • Configure for Devnet

  • Join or create a testnet cluster

  • Deploy your node with Docker

Prerequisites

Before starting, ensure you have the following installed:

You'll also need:

  • A reliable internet connection

  • Basic familiarity with command-line tools

Windows Users: Arcium doesn't run natively on Windows yet, but don't worry! You can use Windows Subsystem for Linux (WSL2) with Ubuntu to follow this guide. It works great and gives you the full Linux experience.

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

Important: 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://arcium-install.arcium.workers.dev/ | 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

Security is crucial for node operations, so we'll create three separate keypairs that each handle different aspects of your node's functionality.

Your ARX node needs three 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

Note: 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

Keep these keypairs safe and private - they're like the master keys to your node. Store them securely and don't share them with anyone.

Step 4: Fund Your Accounts

Now that you have your keypairs set up, your node and callback accounts need some Devnet SOL to pay for transaction fees. Let's get their addresses first, then add some funds.

Your node and callback accounts need Devnet SOL for transaction fees. Get their public keys first:

# Get your node public key
solana address --keypair node-keypair.json

# Get your callback public key
solana address --keypair callback-kp.json

Fund each account using the Solana CLI:

# Fund node account (replace <node-pubkey> with your actual public key)
solana airdrop 2 <node-pubkey> -u devnet

# Fund callback account (replace <callback-pubkey> with your actual public key)
solana airdrop 2 <callback-pubkey> -u devnet

If the airdrop doesn't work: No problem! You can also get Devnet SOL from the web faucet at https://faucet.solana.com/. Just paste your public keys there and request SOL - it's often more reliable than the CLI method.

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.

Tip: Set your Solana CLI to Devnet once so you can avoid passing --rpc-url <rpc-url> repeatedly: solana config set --url https://api.devnet.solana.com

For guidance on choosing a reliable endpoint, see the Devnet 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 \
  --node-offset <your-node-offset> \
  --ip-address <your-node-ip> \
  --rpc-url https://api.devnet.solana.com

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)

  • --node-offset: Think of this as your node's unique ID number on the network. Choose a large random number (like 8-10 digits) to make sure it doesn't conflict with other nodes. 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 Devnet RPC endpoint

Example:

arcium init-arx-accs \
  --keypair-path node-keypair.json \
  --callback-keypair-path callback-kp.json \
  --peer-keypair-path identity.pem \
  --node-offset <your-node-offset> \
  --ip-address <YOUR_PUBLIC_IP> \
  --rpc-url https://api.devnet.solana.com

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

Note: For better reliability, consider using dedicated RPC providers instead of the default public endpoints. See the RPC Provider Recommendations section below.

Step 6: Configure Your Node

Time to tell your node how to behave! The configuration file is like your node's instruction manual - it 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
hardware_claim = 0  # Currently not required to specify, just use 0
starting_epoch = 0
ending_epoch = 9223372036854775807

[network]
address = "0.0.0.0" # Bind to all interfaces for reliability behind NAT/firewalls

[solana]
endpoint_rpc = "<your-rpc-provider-url-here>"  # Replace with your RPC provider URL or use default https://api.devnet.solana.com
endpoint_wss = "<your-rpc-websocket-url-here>"   # Replace with your RPC provider WebSocket URL or use default wss://api.devnet.solana.com
cluster = "Devnet"
commitment.commitment = "confirmed"  # or "processed" or "finalized"

Note: If your node is behind NAT or a cloud firewall, ensure port 8080 is forwarded and allowed inbound on your public IP. Use your public IP for --ip-address during initialization; network.address controls the local bind address. Using "0.0.0.0" ensures the process binds to all local interfaces while peers connect to the public IP you registered during init-arx-accs.

Step 7: Cluster Operations

Here's where things get collaborative! Clusters are groups of nodes that work together on computations during stress testing. You can either start your own cluster and invite others to join, or join an existing cluster that someone else created.

Clusters are groups of nodes that collaborate on MPC computations during stress testing. You have two options for cluster participation. For concepts and roles, see the Clusters Overview.

Option A: Create Your Own Cluster

If you want to create a new cluster and invite other nodes:

arcium init-cluster \
  --keypair-path node-keypair.json \
  --offset <cluster-offset> \
  --max-nodes <max-nodes> \
  --rpc-url https://api.devnet.solana.com

Parameters:

  • --offset: Unique identifier for your cluster (different from your node offset)

  • --max-nodes: Maximum number of nodes in the cluster

Example:

arcium init-cluster \
  --keypair-path node-keypair.json \
  --offset <cluster-offset> \
  --max-nodes 10 \
  --rpc-url https://api.devnet.solana.com

Option B: Join an Existing Cluster

To join an existing cluster, you need to be invited by the cluster authority. Once invited, accept the invitation:

arcium join-cluster true \
  --keypair-path node-keypair.json \
  --node-offset <your-node-offset> \
  --cluster-offset <cluster-offset> \
  --rpc-url https://api.devnet.solana.com

Parameters:

  • true: Accept the join request (use false to reject)

  • --node-offset: Your node's offset

  • --cluster-offset: The cluster's offset you're joining

Step 8: Deploy Your Node

You're almost there! Now we'll get your node up and running using Docker, which packages everything your node needs into a clean, isolated environment.

Run the ARX node container:

8.1 Prepare Log Directory

Before running Docker, create a local directory and log file for the container to write to:

mkdir -p arx-node-logs && touch arx-node-logs/arx.log

This ensures Docker can mount and write logs without permission issues.

8.2 Start the Container

Before running Docker, verify you're in the correct directory and have all required files:

pwd  # Should show: /path/to/arcium-node-setup
ls   # Should show: node-keypair.json, callback-kp.json, identity.pem, node-config.toml, arx-node-logs/

Now start the container:

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 OPERATOR_KEYPAIR_FILE=/usr/arx-node/node-keys/operator_keypair.json \
  -e CALLBACK_AUTHORITY_KEYPAIR_FILE=/usr/arx-node/node-keys/callback_authority_keypair.json \
  -e NODE_CONFIG_PATH=/usr/arx-node/arx/node_config.toml \
  -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)/node-keypair.json:/usr/arx-node/node-keys/operator_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)/arx-node-logs:/usr/arx-node/logs" \
  -p 8080:8080 \
  arcium/arx-node

Notes:

  • The operator keypair uses the same file as your node keypair - this is intentional for simplified testnet setup

  • Ensure port 8080 is open in your OS and cloud provider firewalls for inter-node communication

Tip: Save the same command as a reusable script for convenience:

#!/bin/bash

# Start the ARX node using Docker
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 OPERATOR_KEYPAIR_FILE=/usr/arx-node/node-keys/operator_keypair.json \
  -e CALLBACK_AUTHORITY_KEYPAIR_FILE=/usr/arx-node/node-keys/callback_authority_keypair.json \
  -e NODE_CONFIG_PATH=/usr/arx-node/arx/node_config.toml \
  -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)/node-keypair.json:/usr/arx-node/node-keys/operator_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)/arx-node-logs:/usr/arx-node/logs" \
  -p 8080:8080 \
  arcium/arx-node

Then run it:

chmod +x start.sh
./start.sh

Step 9: Verify Node Operation

Check that your node is running correctly:

Check Node Status

arcium arx-info <your-node-offset> --rpc-url https://api.devnet.solana.com

Check if Node is Active

arcium arx-active <your-node-offset> --rpc-url https://api.devnet.solana.com

Monitor Logs

If using Docker:

docker logs -f arx-node

Devnet RPC Provider Recommendations

For better reliability when running your Testnet node, consider using dedicated RPC providers instead of the default public Solana Devnet endpoints.

Why Use Dedicated RPC Providers

The default public Solana RPC endpoints have limitations that can affect your node's reliability:

  • Transaction Drops: Public RPCs may drop transactions during high network congestion

  • Rate Limits: Stricter limits on requests per second

  • Reliability: No service level agreements or guaranteed uptime

  • Performance: Slower response times compared to dedicated providers

Free tiers are completely sufficient for testnet participation - paid plans are NOT required.

Recommended Free Tier Options:

  • Helius - helius.xyz (free tier works perfectly for testnet)

  • QuickNode - quicknode.com (free tier works perfectly for testnet)

Optional Paid Plans (not needed for testnet):

  • Available from Helius, Triton, or QuickNode if you want enhanced features

The free tiers from Helius and QuickNode provide excellent reliability for testnet stress testing.

Critical Operations Benefiting from Dedicated RPCs

The following operations are particularly sensitive to transaction reliability on Devnet:

  • Node account initialization (init-arx-accs)

  • Cluster creation and management (init-cluster)

  • Cluster joining operations (join-cluster)

  • Real-time node operations and computation handling

What to Expect in Public Testnet

Your node is joining a real testing environment! Here's what you can expect:

  • Real Computations: Your node will actually perform MPC computations to help stress test the network

  • Solana Devnet: Everything runs on Solana's test network, so no real money is involved

  • Stress Testing Purpose: You're helping test how well the network handles scale and performance

  • Variable Activity: Sometimes it'll be busy, sometimes quiet - depends on what's being tested

  • No Rewards Yet: This is pure testing - staking and rewards aren't enabled yet

Think of it as being part of a large-scale rehearsal before the main performance!

For updates on testnet activities and testing schedules, join the Arcium Discord.

Troubleshooting

Common Issues

1. Node Not Starting

  • Verify all keypair files exist and are readable

  • Check that node-config.toml is valid TOML

  • Ensure your IP address is accessible from the internet

2. Account Initialization Failed

  • Verify you have sufficient SOL for transaction fees (at least 1 SOL per account)

  • Check that your RPC endpoint is working

  • Ensure node offset is unique

3. Cannot Join Cluster

  • Verify you've been invited by the cluster authority

  • Check that cluster has available slots

  • Ensure your node is properly initialized

4. Docker Issues

  • Verify Docker is running

  • Check file permissions on mounted volumes

  • Ensure ports are not already in use

Getting Help

If you encounter issues:

  1. Check the Arcium Discord for community support

  2. Review the troubleshooting section in the installation guide

  3. Ensure you're using the latest version of Arcium tooling

Security Best Practices

  • Never share your private keys

  • Store keypairs securely and keep backups

  • Use firewalls to restrict network access

  • Keep your system and Docker images updated

Next Steps

Once your Testnet node is running successfully:

  1. Join the Community: Connect with other node operators on Discord

  2. Stay Updated: Keep your Arcium tooling updated for the latest features

Additional Resources

For questions or support, join our Discord community!

Last updated