🚀 Quick Start Guide

Welcome to Arch Network! Let’s get your first program running in under 15 minutes.

Prerequisites

Before starting, ensure you have the following tools installed:

⚠️ Important: Arch Network now requires Solana CLI 2.x. Please ensure you have version 2.0 or later installed.

Verify your installation:

git --version
rustc --version
solana --version  # Should show 2.x.x or later
arch-cli --version

💡 Note: If you encounter any issues during installation, join our Discord for support.

🚀 Quick Start Project

1. Clone Example Project

# Get the starter example
git clone https://github.com/Arch-Network/arch-examples
cd arch-examples/examples/helloworld

2. Start Local Validator

Choose one of the following network modes:

arch-cli validator-start \
    --network-mode testnet \
    --data-dir ./.arch_data \
    --rpc-bind-ip 127.0.0.1 \
    --rpc-bind-port 9002 \
    --titan-endpoint https://titan-public-http.test.arch.network \
    --titan-socket-endpoint titan-public-tcp.test.arch.network:3030

Option B: Local Development (Regtest)

Prerequisites:

# Use the orchestrate command for full local devnet
arch-cli orchestrate start

This starts a complete local development environment with:

  • Bitcoin Core (regtest mode)
  • Titan indexer
  • Local validator

Option C: Devnet (Full Local Stack)

For devnet, you’ll need to run your own Bitcoin regtest node and Titan indexer:

# 1. Start Bitcoin Core in regtest mode
bitcoind -regtest -port=18444 -rpcport=18443 \
    -rpcuser=bitcoin -rpcpassword=bitcoinpass \
    -fallbackfee=0.001

# 2. First-time setup (only needed once)
# Create a wallet called "testwallet"
bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass createwallet testwallet

# Generate an address and mine the first 100 blocks to it
ADDRESS=$(bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass getnewaddress)
bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass generatetoaddress 100 $ADDRESS

# 3. Clone and build Titan indexer (if not already done)
git clone https://github.com/saturnbtc/Titan.git
cd Titan

# 4. Start Titan indexer pointing to your Bitcoin node
cargo run --bin titan -- \
    --bitcoin-rpc-url http://127.0.0.1:18443 \
    --bitcoin-rpc-username bitcoin \
    --bitcoin-rpc-password bitcoinpass \
    --chain regtest \
    --index-addresses \
    --index-bitcoin-transactions \
    --enable-tcp-subscriptions \
    --main-loop-interval 0 \
    --http-listen 127.0.0.1:3030

# 5. Start validator pointing to your local Titan (in a new terminal)
arch-cli validator-start \
    --network-mode devnet \
    --data-dir ./.arch_data \
    --rpc-bind-ip 127.0.0.1 \
    --rpc-bind-port 9002 \
    --titan-endpoint http://127.0.0.1:3030 \
    --titan-socket-endpoint 127.0.0.1:3030

💡 Note: This option requires you to build and run Bitcoin Core and Titan yourself. For easier local development, use Option B (orchestrate start) instead.

⚠️ First-time setup: The wallet creation and block generation steps are only needed the first time you start bitcoind in regtest mode.

3. Create and Fund Account

Create a new account with the faucet:

# Create account and fund with 1 ARCH (1 billion lamports)
arch-cli account create --keypair-path ./my-account.json --airdrop 1000000000

# Or create account first, then fund separately
arch-cli account create --keypair-path ./my-account.json
arch-cli account airdrop --keypair-path ./my-account.json --amount 1000000000

4. Build and Deploy Your Program

# Navigate to the program directory
cd program

# Build the program using Solana's BPF compiler
cargo build-sbf

# Deploy to the validator
arch-cli deploy ./target/deploy/<program_name>.so --generate-if-missing --fund-authority

# Note: Save your program ID for later use
export PROGRAM_ID=<DEPLOYED_PROGRAM_ADDRESS>

5. Test Your Deployment

# Verify program deployment
arch-cli show $PROGRAM_ID

# Check transaction status
arch-cli tx confirm <TX_ID>

# Get current block height
arch-cli get-block-height

# Get latest block information
arch-cli get-block <BLOCK_HASH>

🔧 Available CLI Commands

Validator Management

# Start local validator
arch-cli validator-start [OPTIONS]

# Orchestrate full local devnet
arch-cli orchestrate start     # Start bitcoind + titan + validator
arch-cli orchestrate stop      # Stop all services
arch-cli orchestrate reset     # Reset entire environment

Account Operations

# Create new account
arch-cli account create --keypair-path <PATH> [--airdrop <AMOUNT>]

# Fund existing account
arch-cli account airdrop --keypair-path <PATH> --amount <LAMPORTS>

# Change account owner
arch-cli account change-owner <ACCOUNT> <NEW_OWNER> <PAYER_KEYPAIR>

# Assign UTXO to account
arch-cli account assign-utxo <ACCOUNT_PUBKEY>

Program Deployment

# Deploy program
arch-cli deploy <ELF_PATH> [--generate-if-missing] [--fund-authority]

# Show account/program info
arch-cli show <ADDRESS>

Transaction Operations

# Confirm transaction status
arch-cli tx confirm <TX_ID>

# Get transaction details
arch-cli tx get <TX_ID>

# View program logs from transaction
arch-cli tx log-program-messages <TX_ID>

Block and Network Info

# Get block by hash
arch-cli get-block <BLOCK_HASH>

# Get current block height
arch-cli get-block-height

# Get group key
arch-cli get-group-key <PUBKEY>

Configuration Profiles

# Create configuration profile
arch-cli config create-profile <NAME> \
    --bitcoin-node-endpoint <URL> \
    --bitcoin-node-username <USER> \
    --bitcoin-node-password <PASS> \
    --bitcoin-network <mainnet|testnet|regtest> \
    --arch-node-url <URL>

# List profiles
arch-cli config list-profiles

# Update profile
arch-cli config update-profile <NAME> [OPTIONS]

# Delete profile
arch-cli config delete-profile <NAME>

🌐 Network Modes

Network ModeDescriptionUse Case
localnetLocal development with regtest BitcoinLocal development and testing
devnetDevelopment networkDevelopment and integration testing
testnetTest network with Bitcoin testnetPre-production testing
mainnetMain production networkProduction use (use with caution)

⚙️ Validator Configuration

Key Parameters

# Basic configuration
--data-dir ./.arch_data                    # Data directory
--network-mode testnet                     # Network mode
--rpc-bind-ip 127.0.0.1                   # RPC bind IP
--rpc-bind-port 9002                      # RPC port

# Titan integration (for testnet/mainnet)
--titan-endpoint <URL>                     # Titan HTTP endpoint
--titan-socket-endpoint <HOST:PORT>        # Titan TCP endpoint

# Performance tuning
--max-tx-pool-size 10000                  # Transaction pool size
--full-snapshot-reccurence 100            # Snapshot frequency
--max-snapshots 5                         # Max snapshots to keep

# Security
--private-key-password <PASSWORD>         # Key encryption password

Environment Variables

You can also use environment variables instead of command-line flags:

export ARCH_NETWORK_MODE=testnet
export ARCH_RPC_BIND_PORT=9002
export ARCH_DATA_DIR=./.arch_data
export ARCH_TITAN_ENDPOINT=https://titan-public-http.test.arch.network

🎮 Next Steps

Congratulations! You’ve successfully deployed your first program. Here’s what you can explore next:

Development

Examples

Production

🆘 Need Help?

📊 System Requirements

Minimum Requirements

  • CPU: 4+ cores
  • RAM: 8GB
  • Storage: 100GB SSD
  • Network: 100 Mbps
  • CPU: 8+ cores
  • RAM: 16GB+
  • Storage: 500GB+ NVMe SSD
  • Network: 1 Gbps

🔍 Common Commands Quick Reference

# Full local development setup
arch-cli orchestrate start

# Deploy and test a program
arch-cli deploy ./target/deploy/program.so --generate-if-missing
arch-cli show <PROGRAM_ADDRESS>
arch-cli tx confirm <TX_ID>

# Account management
arch-cli account create --keypair-path ./account.json --airdrop 1000000000
arch-cli show <ACCOUNT_ADDRESS>

# Network information
arch-cli get-block-height
arch-cli get-block <BLOCK_HASH>

# Stop local environment
arch-cli orchestrate stop