← Back to Docs

Quick Start Guide

The correct order to set up a complete regtest drivechain environment.

Prerequisites

• Bitcoin Core (patched with BIP-300/301) — built and available
• bip300301_enforcer — built and available
• grpcurl installed (for gRPC calls): brew install grpcurl
• All scripts executable: chmod +x scripts/regtest/*.sh

Step-by-Step Setup

Step 1: Start Mainchain Regtest Node

Script: scripts/regtest/1_start_mainchain.sh

./scripts/regtest/1_start_mainchain.sh

This starts Bitcoin Core regtest on port 18443, creates the mainchain wallet, and mines initial blocks to mature coinbase.

Step 2: Start Parentchain Regtest Node (Optional)

Script: scripts/regtest/2_start_parentchain.sh

./scripts/regtest/2_start_parentchain.sh

Starts a separate Bitcoin Core regtest on port 18444 for swap transactions. Only needed if you're testing swap functionality.

Step 3: Start the Enforcer

Script: scripts/regtest/3_start_enforcer.sh

./scripts/regtest/3_start_enforcer.sh

Starts the BIP300301 enforcer, connects to mainchain via RPC and ZMQ, creates the sidechain proposal, and mines 6 blocks for activation.

The enforcer must be running before you can create/unlock the wallet or mine blocks.

Step 4: Create Enforcer Wallet

Script: scripts/regtest/create_enforcer_wallet.sh

# Unencrypted wallet (easiest for testing)
./scripts/regtest/create_enforcer_wallet.sh ""

# Encrypted wallet
./scripts/regtest/create_enforcer_wallet.sh "mypassword"

Creates a new enforcer wallet with a mnemonic. Skip if the enforcer was started with --wallet-auto-create.

Step 5: Unlock Enforcer Wallet

Script: scripts/regtest/unlock_enforcer_wallet.sh

./scripts/regtest/unlock_enforcer_wallet.sh ""

Required before mining or creating transactions. Run after every enforcer restart.

Step 6: Fund Enforcer Wallet (Optional)

Script: scripts/regtest/fund_enforcer_wallet.sh

# Send 1 BTC (default)
./scripts/regtest/fund_enforcer_wallet.sh

# Custom amount
./scripts/regtest/fund_enforcer_wallet.sh 5.0

Only needed for creating deposit transactions. Not required for mining blocks.

Step 7: Mine Blocks

Script: scripts/regtest/mine_with_enforcer.sh

# Mine 1 block
./scripts/regtest/mine_with_enforcer.sh

# Mine 5 blocks, ACK all proposals
./scripts/regtest/mine_with_enforcer.sh 5 true

Complete Workflow (Copy & Paste)

# 1. Start mainchain
./scripts/regtest/1_start_mainchain.sh

# 2. Start enforcer
./scripts/regtest/3_start_enforcer.sh

# 3. Create wallet
./scripts/regtest/create_enforcer_wallet.sh ""

# 4. Unlock wallet
./scripts/regtest/unlock_enforcer_wallet.sh ""

# 5. Mine blocks
./scripts/regtest/mine_with_enforcer.sh 10

# 6. (Optional) Fund wallet for deposits
./scripts/regtest/fund_enforcer_wallet.sh 1.0

Dependency Graph

1_start_mainchain.sh
    ← (no dependencies)

2_start_parentchain.sh
    ← (no dependencies, optional)

3_start_enforcer.sh
    ← Requires: mainchain running

create_enforcer_wallet.sh
    ← Requires: enforcer running

unlock_enforcer_wallet.sh
    ← Requires: enforcer running + wallet exists

fund_enforcer_wallet.sh
    ← Requires: mainchain + enforcer + wallet unlocked

mine_with_enforcer.sh
    ← Requires: enforcer + wallet unlocked

Utility Scripts

Generate Addresses

# Mainchain address
./scripts/regtest/generate_addresses.sh

# Parentchain address
./scripts/regtest/generate_addresses.sh parentchain

# Both chains
./scripts/regtest/generate_addresses.sh both

Send Funds

# From mainchain
./scripts/regtest/send_from.sh mainchain <address> 1.0

# From parentchain
./scripts/regtest/send_from.sh parentchain <address> 0.5

Initialize Test Users (Alice, Bob, Charles)

# Initialize all three users
./scripts/regtest/init_coinshift_app.sh ./test-users all

# Start each user's app
./test-users/alice/start.sh    # RPC 6010 / P2P 4010
./test-users/bob/start.sh      # RPC 6020 / P2P 4020
./test-users/charles/start.sh  # RPC 6030 / P2P 4030

Troubleshooting

• "Mainchain is not running" — Run 1_start_mainchain.sh first
• "Enforcer gRPC is not accessible" — Run 3_start_enforcer.sh and wait for startup
• "Wallet not unlocked" — Run unlock_enforcer_wallet.sh with the correct password
• "Wallet already exists" — Skip creation, just unlock it
• "Insufficient funds" — Mine more blocks or use fund_enforcer_wallet.sh

Stopping Everything

pkill -f bitcoind
pkill -f bip300301_enforcer