Igra Network Community

⚠️ *Heads-up for RPC node operators on kaswallet v3.0.2 and older — protect your wallet keys* *Who this is for:* anyone running an IGRA node with *kaswallet v3.0.2 or earlier* that serves *RPC and submits transactions* — i.e. your worker wallets are *funded*. Those are the wallets most worth protecting here. *The issue (rare, but it can cause key loss):* kaswallet ≤ v3.0.2 rewrites keys.json *in place* on every address/index update. In an uncommon timing window, if the process is killed *during* that write (e.g. a container/dependency restart landing mid-save), the file can be left *truncated to 0 bytes*. Without a backup or your mnemonic, that wallet — *and any funds in it* — become *unrecoverable*. It's rare, but funded RPC wallets write keys.json often, so they're the most exposed. *① Check your kaswallet version* — it's the Docker image tag. From your igra-orchestra directory: grep KASWALLET_VERSION .env # the version you've pinned docker compose images | grep kaswallet # the image your workers are actually running • *3.0.2 or lower* ➜ affected — follow the steps below. • *3.0.3 or higher* ➜ you already have the fix (just make sure you've done the key-directory migration). • *3.0* (a floating tag) ➜ could be either; treat as affected and pin KASWALLET_VERSION=3.0.3 explicitly to be sure. *② Back up your keys now — do this regardless of version.* An encrypted, off-box backup of your keys/ directory (or at least your mnemonics) fully protects you against this bug today. tar czf keys-backup-$(date +%F).tgz keys/ # then move it off the box and encrypt/store it safely *③ Upgrade to kaswallet v3.0.3 — the permanent fix.* v3.0.3 writes keys.json *atomically* (temp file ➜ fsync ➜ rename), so an interrupted save can never truncate your key file again. The atomic write needs a per-worker *directory* mount, so the upgrade includes a one-time key migration. On each node: ⚠️ *Stop your frontend workers FIRST*, before you migrate or upgrade. Nothing must be writing keys during the move (the migration tool will refuse to run while a wallet is live). 1\. *Stop the frontend* (kaswallet-* / rpc-provider-*). docker compose --profile frontend-wN down # your worker profile, e.g. frontend-w5 2\. *Migrate* the keys (moves keys/keys.kaswallet-N.json ➜ keys/kaswallet-N/keys.json). 3\. *Recreate + pull the new image:* docker compose --profile frontend-wN up -d --pull always # your worker profile, e.g. frontend-w5 📖 [Full step-by-step with verification + troubleshooting](https://github.com/IgraLabs/igra-orchestra/blob/main/doc/node-operations/migrate-keys-to-directory-mounts.md) ⚠️ *Don't just pull the v3.0.3 image without migrating* — a node still on the old single-file key mount will crash-loop until you migrate (no key loss, but the wallet won't run). Questions or want a hand upgrading? Drop them here. 🙏