BlockDAG Node Setup Documentation

Automation helpers for running and maintaining a BlockDAG testnet node with Docker. The scripts wrap the provided docker-compose.yml so you can bring a node up with a single command, manage restarts, and safely wipe local state when needed.

Table of Contents

• Features
• Repository Layout
• Requirements
• Setup
• Running the Node
• Maintenance Tasks
• Troubleshooting
• Data & Security Notes
• Reference: Docker Compose Service
• Support

---

Features

• Single-entrypoint script (blockdag.sh) that loads your mining address and launches Docker Compose.
• Cross-platform Docker Compose detection (node.sh) compatible with Compose v1 and v2 syntaxes.
• Opinionated directory structure for persisted blockchain data, logs, and binaries under bin/bdag/.
• Sample environment file (.env) for storing wallet configuration.
• Optional Linux helper to install Docker & Docker Compose (install_docker.sh).

---

Repository Layout

blockdag.sh             # Primary launcher – loads wallet and calls node.sh
node.sh                 # Starts docker compose with the provided mining address
restart.sh              # Stops current stack, removes image, restarts with existing data
restartWithCleanup.sh   # Same as above, but wipes ./bin/bdag before restart
stop.sh                 # Stops running containers for a specific role or all roles
install_docker.sh       # Ubuntu-based helper to install Docker & docker-compose
docker-compose.yml      # Defines the BlockDAG worker service and persisted volumes
bin/bdag/data           # Blockchain data volume (created at runtime)
bin/bdag/logs           # Node log output (created at runtime)
.env                    # Optional environment file (example provided)
wallet.txt              # Optional file containing wallet info, last line read as mining address

Note: bin/bdag/data and bin/bdag/logs may be empty until the node runs. If they contain testnet data generated by previous runs, they might require elevated permissions to inspect or delete.

---

Requirements

Operating Systems

• Linux (Ubuntu/Debian, Fedora, Arch, etc.): fully supported. Scripts assume a POSIX shell and Docker.
• macOS (Ventura 13+ recommended): supported as long as Docker Desktop is installed.
• Windows: run inside WSL2 or another Linux-like environment. Native PowerShell is not supported by these scripts.

Software

• Docker Engine & Docker Compose v1 or v2.
• Git (to clone the repository).
• bash (all scripts use Bash features).

Optional for Linux users:

• curl, apt, etc. – install_docker.sh targets Ubuntu 20.04+ and requires root.

Hardware Guidelines

• CPU: Minimum 4 cores (4+ cores recommended for mining).
• Memory (RAM): At least 8GB (8GB+ recommended).
• Disk Space: Minimum 20GB of free disk space. More storage is recommended depending on the size of the blockchain and logs.
• Network: A stable internet connection with sufficient bandwidth.

Wallet Format Notice

• BlockDAG nodes now use EVM-compatible public addresses (0x…) for mining rewards.
• Legacy UTXO-based PK addresses are no longer supported. Update any automation, scripts, or stored credentials to point to an EVM wallet before starting the node.

---

Setup

1. Clone the repository

   git clone https://github.com/BlockdagNetworkLabs/blockdag-scripts.git
   cd blockdag-scripts

2. Configure your mining address

   • Option A: edit .env and set PUB_ETH_ADDR=<your_evm_wallet_address>.
   • Option B: create wallet.txt where the last line contains your wallet address (e.g. exported from another tool).

   If both exist, .env takes precedence.

   Network note: These scripts target the latest EVM-based BlockDAG network only. Do not reuse legacy UTXO addresses; configure a 0x-prefixed EVM wallet for mining rewards.

3. Verify Docker access

   docker --version
   docker compose version  # or docker-compose --version

   If Docker is not installed on Ubuntu, you can adapt the provided install_docker.sh script (requires sudo).

4. Allow Docker to create local directories Ensure your user has permissions to write to bin/bdag/. The directory is created automatically, but on Linux you may need to chown it if Docker runs as root.

5. Configure your mining address

   • Option A: edit .env and set PUB_ETH_ADDR=<your_evm_wallet_address>.
   • Option B: create wallet.txt where the last line contains your wallet address (e.g. exported from another tool).

Address Format Update (EVM Only)

• BlockDAG mining rewards are now paid to Ethereum-style accounts. Supply an 0x-prefixed EVM public address wherever the scripts expect PUB_ETH_ADDR.
• If you are migrating from earlier releases that referenced UTXO/PK addresses, regenerate or import an EVM wallet and update .env or wallet.txt accordingly.
• Remove any legacy environment variables or files that still contain the deprecated address format to avoid accidental misconfiguration.

---

Running the Node

1. Launch the node (prompts will depend on your shell configuration): Choose a role or omit it to default to the miner archive template:

   ./blockdag.sh               # default miner node
   ./blockdag.sh full          # validation without mining
   ./blockdag.sh relay         # gateway relay mode

   The script resolves your address, exports it as PUB_ETH_ADDR, selects the matching compose file, and calls node.sh. Set NODE_ROLE=` in your environment if you prefer not to pass a CLI argument.

2. node.sh selects the correct Docker Compose syntax for your installation and starts the stack with MINING_ADDRESS set from your EVM wallet.

3. Once the containers are up:

   docker ps            # Verify the blockdag-testnet-network container is running
   tail -f bin/bdag/logs/node.log  # Replace with actual filename after first run

To stop the node without cleaning data:

docker compose down    # or docker-compose down

---

Node Types & Compose Configurations

This repository now ships dedicated Docker Compose files for each supported node role. All templates default to EVM archive mode so historical chain state is preserved out of the box. If you prefer a pruned node, remove --gcmode=archive from the corresponding NODE_ARGS before launching.

Node type	Compose file	Highlights
Miner	docker-compose.yml	Enables mining via --miner/--generate and exposes JSON-RPC/WebSocket endpoints for local tooling.
Full	docker-compose.full.yml	Syncs and validates the network without mining.
Relay	docker-compose.relay.yml	Runs the gateway stack (--gateway) to proxy DAG/EVM traffic for external clients.

Tip: Any of the non-archive templates can double as an archive node just by keeping the default --gcmode=archive. Removing that flag reverts to the previous pruned behaviour.

To start a specific role with the helper script, run ./blockdag.sh <role>. For example, ./blockdag.sh relay loads docker-compose.relay.yml while ./blockdag.sh full launches the docker-compose.full.yml. Use ./blockdag.sh to fall back to the default docker-compose.yml miner node.

Launching a specific node type

1. Copy the compose file that matches your desired role or reference it directly when starting Docker Compose. For example, to run a miner node in archive mode:

   MINING_ADDRESS=$PUB_ETH_ADDR docker compose -f docker-compose.miner.yml up -d

2. Follow the same pattern for the other node types by substituting the compose file.

3. When archive storage is not required, edit the chosen compose file and remove --gcmode=archive from the embedded --evmenv string before launching.

Refer to the Additional Note below for more context on the archive flag and recommended hardware for long-term archive deployments.

---

Maintenance Tasks

Use the helper scripts at the repository root:

• stop.sh [role|all] – stops containers for the selected role (defaults to miner). Pass all to shut down miner, full, and relay stacks in one go.
• restart.sh [role] – shuts down Docker Compose for the selected role (defaults to miner), removes the image referenced by the compose file, and relaunches using your configured wallet.
• restartWithCleanup.sh [role] – same as above but also clears ./bin/bdag/* (data, logs, any cached binaries). Back up your wallet before running this.
• install_docker.sh – Ubuntu/WSL convenience installer. Review the script before executing (sudo ./install_docker.sh).

Manual alternatives:

# Pull the latest image
MINING_ADDRESS=$PUB_ETH_ADDR docker compose pull

# View logs
docker compose logs -f

# Remove volumes and containers
docker compose down --volumes

---

Troubleshooting

• "PUB_ETH_ADDR not set": Confirm .env or wallet.txt exists and the address is on the last line. Reload your shell if you edited .env while a session was running.
• Docker permission denied: Add your user to the docker group (sudo usermod -aG docker $USER) and restart your session, or run the scripts with sudo.
• Node restarts on launch: Inspect bin/bdag/logs for recent log files. If corruption errors appear, run ./restartWithCleanup.sh to wipe local state.
• Port conflicts: Default ports 38131, 18545, 18546, and 18150 must be free. Stop other services using them or edit docker-compose.yml.
• Windows path issues: Ensure the repository lives inside your WSL filesystem (e.g. /home/<user>), not the mounted C: drive, to avoid Docker volume permission problems.

---

Data & Security Notes

• The wallet address (PUB_ETH_ADDR) is injected into the container as MINING_ADDRESS. It must be an EVM address; do not reuse retired UTXO-style identifiers.
• Do not commit .env or wallet.txt with real keys.
• Blockchain data persists in bin/bdag/data/. Back it up before destructive operations.
• Logs populate bin/bdag/logs/ and may contain sensitive operational details; sanitize before sharing.
• Consider rotating Docker logs or mounting external storage if running long-term.

docker-compose.yml launches a single service named nodeworker based on abhishek1857/blockdag:worker-20250923-102625. Key settings:

Reference: Docker Compose Service

docker-compose.yml launches a single service named nodeworker based on blockdagnetwork/awakening:v0.0.3. Key settings:

• Ports: 38131 (RPC), 18545 (HTTP), 18546 (WebSocket), 18150 (peer).
• Volumes:
  • bdag_bin named volume mounted at /opt/bdag inside the container.
  • Local ./bin/bdag/data → /bdag/data for chain data.
  • Local ./bin/bdag/logs → /bdag/logs for logs.
• Environment: NODE_ARGS assembles testnet flags, mining options, CORS/websocket settings, and seeds a peer.

Customize the image tag or arguments directly in docker-compose.yml if the network releases new versions.