Arcium Node Setup

This repository contains a complete setup for running an Arcium ARX node on the Solana Devnet testnet. The node is configured to participate in MPC (Multi-Party Computation) computations within a cluster.

Prerequisites

Before setting up your node, ensure you have the following installed:

• Docker & Docker Compose
• Solana CLI
• OpenSSL
• Git
• Python 3 (for wallet creation script)

System Dependencies (Ubuntu/Debian)

If you're on Ubuntu or Debian, you can install the required system dependencies with:

sudo apt update
sudo apt install -y docker.io docker-compose openssl curl git python3 python3-pip netstat ss lsof
sudo usermod -aG docker $USER

After running these commands, you may need to log out and log back in for the Docker group changes to take effect.

Python Dependencies

Install the required Python dependencies:

pip3 install -r requirements.txt

Or if you prefer to install them manually:

pip3 install base58

Initial Setup

Setting Script Permissions

The scripts in this repository need to be executable to function properly. To set the correct permissions, run:

chmod +x start-arcium-node.sh view-logs.sh create_wallet_from_private_key.py generate_wallet.py generate_offset.py show_offset.py

Getting Your IP Address

To get your public IP address, you can use one of these commands:

# Get your public IP
curl ifconfig.me

# Alternative command
curl ipinfo.io/ip

# Get your local IP
hostname -I

Node Configuration

The node requires several keypair and configuration files. These files are automatically generated when you run the setup scripts:

• node-keypair.json - Node authority keypair
• callback-kp.json - Callback authority keypair
• identity.pem - Node identity keypair (PKCS#8 format)
• node-config.toml - Node configuration file (generated from template)

Note: The node offset can be configured in two ways:

1. Environment variable: Set NODE_OFFSET environment variable before starting the node (will update the generated config file)
2. Generated automatically: If no NODE_OFFSET is set and the offset in the template is 0, a random offset will be generated

The environment variable takes precedence over the generated value.

Important: The required files are automatically generated when you run the setup scripts described below. The node-config.toml file contains your actual node offset and should not be shared publicly.

Node Offset Management

The node offset is a unique identifier for your Arcium node. It can be managed automatically by the start script or manually using helper scripts:

Show current node offset:

python3 show_offset.py

This script displays the current node offset, checking first for the NODE_OFFSET environment variable, then falling back to the value in node-config.toml.

Generate a new node offset (manual):

python3 generate_offset.py

This script generates a random large number and updates your node-config.toml file.

Note: The start script automatically handles offset generation and management, so you typically don't need to run these scripts manually. Set the NODE_OFFSET environment variable before starting the node if you want to use a specific offset.

Setup Process

1. Create Your Wallet

You can either generate a new wallet or import an existing private key:

Option 1: Generate a new wallet (recommended for new users)

python3 generate_wallet.py

Option 2: Import an existing private key

python3 create_wallet_from_private_key.py <your_private_key>

Both options will create a user-wallet.json file that you can use to fund your node accounts.

Note: The wallet creation scripts automatically generate all required keypair files:

• user-wallet.json - Your personal wallet
• node-keypair.json - Node authority keypair
• callback-kp.json - Callback authority keypair
• burner-wallet.json - Test wallet

The identity.pem file is automatically generated by the start script if missing.

2. Fund Your Accounts

You need to fund the node and callback accounts with Devnet SOL:

# 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 (replace with your actual public keys)
solana airdrop 2 <node_pubkey> -u devnet
solana airdrop 2 <callback_pubkey> -u devnet

If airdrops don't work, use the Solana web faucet at https://faucet.solana.com/

3. Initialize Node Accounts

Initialize your node accounts on the blockchain:

solana config set --url https://api.devnet.solana.com

# Automatically get your public IP address
PUBLIC_IP=$(curl -s ifconfig.me)

arcium init-arx-accs \
  --keypair-path node-keypair.json \
  --callback-keypair-path callback-kp.json \
  --peer-keypair-path identity.pem \
  --node-offset $(grep "^offset = " node-config.toml | cut -d '=' -f 2 | tr -d ' ') \
  --ip-address $PUBLIC_IP \
  --rpc-url https://api.devnet.solana.com

Note: The command above automatically retrieves your public IP address. If you prefer to set a specific IP address, replace $PUBLIC_IP with your desired IP. For nodes running behind NAT or on private networks, you may need to specify your public IP manually.

4. Join a Cluster

You can either join an existing cluster or create your own:

Join existing cluster:

# Automatically get your public IP address
PUBLIC_IP=$(curl -s ifconfig.me)

arcium join-cluster true \
  --keypair-path node-keypair.json \
  --node-offset $(grep "^offset = " node-config.toml | cut -d '=' -f 2 | tr -d ' ') \
  --cluster-offset <cluster_offset> \
  --ip-address $PUBLIC_IP \
  --rpc-url https://api.devnet.solana.com

Create your own cluster:

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

Note: The join-cluster command automatically retrieves your public IP address. For nodes running behind NAT or on private networks, you may need to specify your public IP manually by editing the --ip-address parameter.

5. Start the Node

Use the provided script to start the node with automatic port checking:

./start-arcium-node.sh

Or use Docker Compose directly:

docker-compose up -d

Note: The start script automatically:

• Checks for required dependencies (docker, openssl, python3)
• Generates the identity.pem file if it's missing
• Generates the node-config.toml file from node-config.template if it's missing
• Uses the NODE_OFFSET environment variable if set, otherwise generates a new offset if the template has offset = 0
• Updates the node offset in the configuration file based on the NODE_OFFSET environment variable
• Checks for available ports using multiple tools (netstat, ss, lsof) with fallbacks

The generated node-config.toml file will contain your actual node offset value.

Monitoring

Check if your node is active:

arcium arx-active $(grep "^offset = " node-config.toml | cut -d '=' -f 2 | tr -d ' ') --rpc-url https://api.devnet.solana.com

View node information:

arcium arx-info $(grep "^offset = " node-config.toml | cut -d '=' -f 2 | tr -d ' ') --rpc-url https://api.devnet.solana.com

Check logs:

The recommended way to view logs is using the provided script which handles both Docker and file-based logs:

# View recent logs and follow new entries
./view-logs.sh

# View complete log history
./view-logs.sh --history

Alternative methods (less recommended):

# Direct file logs (if not using Docker)
tail -f arx-node-logs/arx_log_*.log

# Docker logs (may be empty as the node writes to files)
docker logs -f arx-node

Troubleshooting

If the node doesn't start:

1. Check that all required ports are available
2. Verify all configuration files are present
3. Ensure your wallet is funded with sufficient SOL
4. Check the logs for specific error messages

Security

• Keep all keypair files secure and private
• Don't share your private keys with anyone
• The node keys are like master keys to your node
• Store backups of your keypairs in secure locations
• Use environment variables for sensitive values like NODE_OFFSET
• The node-config.toml file is automatically generated and excluded from version control via .gitignore
• Always keep your node-config.template file with safe default values (offset = 0) in version control