# How to add validator to DOS Chain with WSL

## Avalanche + Ledger trong WSL (Windows 11) — Hướng dẫn đầy đủ

> Tài liệu này giúp thiết lập và kiểm thử ký giao dịch Avalanche bằng Ledger (Nano S/S+/X hoặc Stax) trong WSL2 (Ubuntu) trên Windows 11. Các bước chỉ đọc/kiểm thử đều không broadcast, an toàn để chạy.

***

### 0) Điều kiện

* Windows 11 + WSL2 (Ubuntu 22.04/24.04 hoặc 24.10).
* Ledger đã cài **Avalanche app** trong Ledger Live.
* Khi ký thật: **đóng Ledger Live** và mọi ví trên Windows.

***

### 1) Cài `usbipd` (Windows) và passthrough Ledger cho WSL

Mở **PowerShell (Run as Administrator)**:

```powershell
# Cài usbipd
winget install usbipd

# Liệt kê USB để tìm Ledger (VID 2c97)
usbipd list

# Bind (chỉ làm lần đầu cho thiết bị đó)
usbipd bind --busid <BUSID>

# Attach vào WSL (mỗi lần cắm lại hoặc sau reboot Windows)
usbipd attach --wsl --busid <BUSID>

# Kiểm tra lại
usbipd list
```

Trong **WSL (Ubuntu)** xác nhận thiết bị đã vào:

```bash
lsusb | grep -i 2c97          # thấy 2c97:xxxx (Stax: 6000, Nano X: 4000)
ls -l /dev/hidraw*            # có hidraw node
```

***

### 2) Bật systemd trong WSL (để udev hoạt động chuẩn)

Trong **WSL (Ubuntu)**:

```bash
sudo tee /etc/wsl.conf >/dev/null <<'INI'
[boot]
systemd=true
INI
```

Trên **Windows (PowerShell)**:

```powershell
wsl --shutdown
```

Mở lại **Ubuntu WSL**, kiểm tra:

```bash
systemctl status systemd-udevd   # phải active (running)
```

***

### 3) Cài Avalanche-CLI trong WSL

```bash
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s

# Đảm bảo ~/bin đã có trong PATH (idempotent đã cấu hình ở ~/.bashrc)
source ~/.bashrc

avalanche --version
```

***

### 4) Udev rules cho Ledger trong WSL

```bash
# Cài rules chính thức từ LedgerHQ
curl -fsSL https://raw.githubusercontent.com/LedgerHQ/udev-rules/master/add_udev_rules.sh | sudo bash

# Đảm bảo user thuộc nhóm plugdev
getent group plugdev || sudo groupadd plugdev
sudo usermod -aG plugdev "$USER"

# Áp rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# Nếu vừa thêm group: đóng WSL rồi mở lại (Windows: wsl --shutdown)
```

Kỳ vọng sau khi re-attach Ledger:

```bash
ls -l /dev/hidraw*
# Ví dụ:
# crw-rw---- 1 root plugdev ... /dev/hidraw0
# crw-rw---- 1 root plugdev ... /dev/hidraw1
```

***

### 5) Kiểm thử an toàn (không ký, không broadcast)

#### 5.1 Kiểm HID mở được (Python, tùy chọn)

```bash
python3 - <<'PY'
import hid, sys
V, P = 0x2c97, 0x6000  # Stax; nếu Nano X: P=0x4000
devs = [d for d in hid.enumerate(V, P)]
print("Found", len(devs), "Ledger interface(s)")
try:
    h = hid.device()
    h.open(V, P)  # chỉ open, không gửi APDU
    print("HID OPEN OK")
    h.close()
except Exception as e:
    print("HID OPEN FAIL:", e); sys.exit(2)
PY
```

#### 5.2 Liệt kê địa chỉ trên Fuji (chỉ đọc)

> Mở khóa Ledger và mở **app Avalanche** trước.

```bash
avalanche key list --ledger 0 --fuji
```

#### 5.3 Liệt kê địa chỉ Mainnet bằng alias (chỉ đọc)

```bash
# Đặt tên (alias) cho index 0 trên Ledger — chỉ tạo bí danh cục bộ, không tạo private key
avalanche key import ledger --name stax0 --ledger 0

# Liệt kê địa chỉ theo tên trên mainnet
avalanche key list --keys stax0 --mainnet
```

***

### 6) (Tùy chọn) Import metadata blockchain vào local

Không bắt buộc. Dùng khi muốn đặt tên và tái sử dụng cấu hình chain gọn hơn. Nếu bản CLI hỗ trợ:

```bash
avalanche blockchain import \
  --rpc https://main.doschain.com \
  --blockchain-id 22v7AG7h6qaVxd4bLvAsSsg2LZ4RCn5iVYgFn7a2Fj1LCuYwjv \
  --name dos-main

avalanche blockchain list
avalanche blockchain describe dos-main
```

Sau đó có thể dùng `dos-main` thay cho `--rpc`/`--blockchain-id` trong các lệnh khác.\
Nếu CLI của bạn chưa có `blockchain import`, bỏ qua bước này (không ảnh hưởng thao tác qua `--rpc`).

***

### 7) Ký Add Validator (khi cần)

Chuẩn bị Ledger: mở khóa PIN, vào **app Avalanche**.

```bash
unset LEDGER_DEVICE
# Dùng trực tiếp RPC:
avalanche blockchain addValidator --rpc https://main.doschain.com

# Hoặc nếu đã import và đặt tên:
# avalanche blockchain addValidator --blockchain-name dos-main
```

Điền: **Mainnet**, BlockchainID (nếu chưa import), NodeID, Weight, Start/End time. Xác nhận ký trên Ledger.

***

### 8) Kiểm tra trạng thái

```bash
avalanche blockchain list
avalanche blockchain describe "TEN_BLOCKCHAIN"
avalanche blockchain validators "TEN_BLOCKCHAIN" --mainnet
avalanche blockchain stats "TEN_BLOCKCHAIN" --mainnet
```

***

### 9) Sau mỗi lần reboot Windows

```powershell
# PowerShell (Run as Administrator)
usbipd attach --wsl --busid <BUSID>
```

Rồi vào WSL xác nhận `lsusb | grep -i 2c97`.

***

### 10) Troubleshooting nhanh

* **WSL không thấy Ledger**
  * Windows: `usbipd list` → `usbipd attach --wsl --busid <BUSID>`
  * WSL: `lsusb | grep -i 2c97`, kiểm tra `/dev/hidraw*`
* **`hidapi: failed to open device`**
  * `systemd-udevd` phải running
  * `/dev/hidraw*` phải `root:plugdev` và `0660`
  * User thuộc `plugdev`
  * Đóng Ledger Live và ví khác trên Windows
  * Rút cắm lại, rồi:

    ```powershell
    usbipd detach --busid <BUSID>
    usbipd attach --wsl  --busid <BUSID>
    ```
  * Có thể bật log:

    ```bash
    LEDGER_LOG_LEVEL=debug avalanche blockchain addValidator --rpc https://main.doschain.com
    ```
* **`avalanche` không vào PATH**
  * `source ~/.bashrc`
  * Đảm bảo cuối file chỉ có **một** khối idempotent thêm `~/bin`.

***

### Phụ lục: Mẫu khối PATH idempotent cho `~/.bashrc`

```bash
# ensure ~/bin is in PATH (idempotent)
case ":$PATH:" in
  *":$HOME/bin:"*) ;;
  *) export PATH="$HOME/bin:$PATH" ;;
esac
```

***

**Ghi chú:** Không bắt buộc “import blockchain về local.” Dùng `--rpc` là thao tác được ngay. Import chỉ để đặt tên, lưu metadata cục bộ cho tiện dùng lại.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.doschain.com/validators/how-to-add-validator-to-dos-chain-with-wsl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.