# Node Setup Guide

Automation helpers for running and maintaining a BlockDAG mainnet 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
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](https://learn.microsoft.com/windows/wsl/install) 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.<br>

### Setup

1. **Clone the repository**

   ```bash
   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**

   ```bash
   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.<br>

### 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.<br>

### Running the Node

1. Launch the node (prompts will depend on your shell configuration):

   ```bash
   ./blockdag.sh
   ```

   The script resolves your address, exports it as `PUB_ETH_ADDR`, and calls `node.sh`.
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:

   ```bash
   docker ps            # Verify the blockdag-mainnet-network container is running
   docker logs -f <CONTAINER_NAME>  # Replace with actual container
   ```

To stop the node without cleaning data:

```bash
docker compose down    # or docker-compose down
```

### Maintenance Tasks

Use the helper scripts at the repository root:

* `restart.sh` – shuts down Docker Compose, removes the `blockdagnetwork/awakening` image if present, and relaunches using your configured wallet.
* `restartWithCleanup.sh` – 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:

```bash
# 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.<br>

### 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.<br>

### Reference: Docker Compose Service

`docker-compose.yml` launches a single service named `nodeworker` based on `abhishek1857/blockdag:worker-20250923-102625`. 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 mainnet 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.