# Canonical QBFT Validator Host Migration

## Objective

Move the four active QBFT validator identities from one Windows host to four
independent LAN/VPN hosts without changing the canonical genesis, chain ID,
validator addresses, or block history.

This is a host migration, not a new-network launch. The active genesis SHA-256
is recorded by the initializer and every package verifies it before starting.

## Safety invariants

- Never run the same validator private key on two hosts at once.
- Never mix files from runtime/plais-qbft-distributed into the canonical
  network. That directory has a different genesis and different validator keys.
- Keep at least three of the four canonical validators online during each move.
- Validators expose P2P only. HTTP RPC stays on the RPC node and remains bound
  to loopback.
- P2P firewall rules allow only the four declared private LAN/VPN addresses.
- Install pre-sync packages first. Validator packages require a separate
  activation approval file and do not start merely because they were installed.

## Current prepared state

The initializer creates the ignored file
runtime/plais-qbft-canonical-migration/topology.json. It contains the four
current validator public identities and the canonical genesis hash, but no new
private keys. Its initial state is AWAITING_PRIVATE_NETWORK_ADDRESSES.

## Required network inputs

Use stable private LAN or VPN addresses only. Public Internet addresses,
loopback addresses, hostnames, and duplicate validator hosts are rejected.

AISFOR storage nodes mirror signed private-address evidence from their existing
gateway registration. Inspect the four declared PCs and test gateway
reachability from the bridge with:

    npm run evm:inventory-validator-hosts

Reported home-LAN addresses are evidence only. Do not place them in the
migration topology unless the bridge can route to them. A shared LAN/VPN must
provide four unique, stable addresses and a private address on the bridge.

1. Set bridge.advertisedHost to the current QBFT host's reachable private
   address.
2. Set one unique targetHost for each of the four validators.
3. Confirm TCP P2P reachability between those hosts. Do not expose RPC 8545.

Then run:

    npm run evm:finalize-canonical-migration

Before finalization or package transfer, validate the Windows installer,
canonical runtime layout, validator-key ACL, preflight, and activation lock with:

    npm run evm:test-deployment-tooling

The tooling self-test uses a disposable synthetic package and never starts a
validator or reads a canonical validator private key.

Finalization revalidates every current private key against its public key and
validator address. It creates ignored pre-sync and cutover packages under
runtime/plais-qbft-canonical-migration/packages. It refuses to overwrite an
existing private-key package.

## Bridge phase

Before any remote pre-sync node starts:

1. Install the restricted bridge firewall rules with
   deploy/qbft-canonical/enable-bridge-firewall.ps1.
2. Set PLAIS_QBFT_BRIDGE_CONFIG to the generated bridge-topology.json.
3. Restart the local QBFT nodes one at a time, verifying block production after
   every restart. Never restart all validators together.

Bridge mode preserves the same node data and private keys. It changes only P2P
binding and the static peer list. The RPC HTTP interface remains loopback-only.

## Pre-sync phase

On each target PC, transfer only its matching presync package and the common
Besu/JDK runtime. Run install-node.ps1, then run preflight-node.ps1 with
RequirePeerReachability. Start the pre-sync role and wait until its height
matches the canonical RPC. A pre-sync node is not a validator and has no
canonical validator private key.

## One-at-a-time cutover

For validator N:

1. Confirm the remote pre-sync node is fully caught up.
2. Stop that remote pre-sync process.
3. Install its matching validator package into the same install root. The
   synchronized data directory is preserved.
4. Stop only local plais-qbft-validator-N and confirm the chain still advances
   with three validators.
5. Run approve-node-activation.ps1 on the remote host, typing the expected
   validator address from node-config.json.
6. Start the remote validator. Confirm the same validator address, peer identity,
   canonical height, and fresh blocks.
7. Observe at least ten minutes before moving the next identity.

If the remote validator fails, stop it before restarting the matching local
validator. Never allow both copies of one identity to run concurrently.

## Completion gate

Run:

    npm run evm:check-host-distribution

The check reads live admin_peers, matches peer IDs against the four current
validator public keys, and counts unique remote IP addresses. Completion
requires canonical RPC online, four QBFT validators, four matching validator
peer identities, four independent validator host addresses, continued block
production, and the external-transfer and legacy-write locks.

Only after the live result reports 4/4 may validator_host_distribution pass.

## Key custody

Validator packages contain one private key each. Transfer each package through
an encrypted operator channel to its assigned PC, verify the manifest, install
it under the intended service account, and remove transport copies. The
installer disables ACL inheritance and grants access only to that account,
SYSTEM, and local Administrators. Do not place packages in source control,
shared drives, chat, email, or public cloud storage.
