Migration & compatibility

Current migration policy

Protocol v2 testnet is a clean network, not an in-place upgrade from the prototype/v1 chain. Old block files, RocksDB state, Redis entries, P2P peers, balances, and transaction IDs are incompatible.

The safe rule is:

preserve old data read-only
start protocol v2 in a new empty network directory
restore only intentional wallet recovery material

Do not attempt to make old state “work” by editing version bytes, index entries, or genesis identifiers.

Compatibility matrix

Artifact/interface	Compatible within current v2 alpha?	Compatible from prototype/v1?
18-byte P2P VERSION	yes, protocol 2 + same chain	no
transaction v1 213-byte body	yes while format/rules unchanged	do not assume
block v1 serialization	yes within clean v2 history	do not assume
four-byte early-v2 block location	lazily upgraded	not evidence of v1 support
17-byte block location v1	current	no general conversion
accounts/chainstate RocksDB	release-specific current directory	no
Redis mempool keys	disposable current policy	no; clear/use isolated DB
Explorer API v1	client-compatible if contract remains additive	not a chain-data migration
Explorer SQLite schema v1	identity-checked/rebuildable	rebuild from current canonical chain
wallet vault v1	current wallet validates/decrypts supported record	only if its cryptography/record matches exactly
mnemonic/private key	cryptographically recoverable where derivation matches	preserve intentionally; old balances do not transfer
Astro website	static deployment independent of node data	rebuild against current API contract

Compatibility is never inferred solely from matching a filename or major version number.

Clean v2 node migration

1. Stop every old node, miner, wallet gateway, and explorer-index process.
2. Record the old software revision, network, data directory, ports, Redis DB, and tip ID for provenance.
3. Back up only the recovery material and old data you intentionally need.
4. Make the entire old directory read-only or move it outside active service paths.
5. Choose a new explicit v2 directory:

luracoin node \
  --network testnet \
  --data-dir ~/.luracoin/testnet-v2 \
  --port 9999

6. Use a Redis DB that contains no prototype entries; testnet defaults to DB 1, but a dedicated instance/DB is clearer when preserving old services.
7. Connect only to protocol-v2 peers on the same chain ID.
8. Verify reconstructed genesis ID before accepting any balance/history as current.
9. Point wallet and explorer tooling to the exact new network/data context.
10. Retain the old directory until the migration has been reviewed; do not merge its files into v2.

What wallet recovery preserves

A valid 24-word mnemonic using the implemented BIP39 passphrase and root derivation preserves the corresponding private/public key and address.

It does not preserve:

• balances from an obsolete test chain;
• old transaction confirmations or IDs;
• pending Redis transactions;
• address history on a new genesis;
• contacts/preferences unless separately exported;
• assurance that a prototype used the same derivation rules.

Verify a restored address before discarding any previous wallet backup. Never type recovery words into node CLI logs, web forms, or migration scripts you have not audited.

Point Electron at the new node

The official desktop wallet locates the token in the selected network data directory. Launch it with the same explicit directory context used by the node, for example:

export LURACOIN_DATA_DIR="$HOME/.luracoin/testnet-v2"
cd luracoin-wallet
npm run desktop

Confirm in the UI and /v1/status that:

• network is testnet;
• chain ID is 1;
• data directory is the intended v2 path;
• node is initialized and expected tip/genesis ID matches;
• ready and mempool_available are true before sending.

The wallet intentionally normalizes unsupported/old mainnet preference values back to testnet.

P2P v1 to v2 boundary

Prototype P2P used a 14-byte handshake without chain ID. Current v2 requires exactly 18 bytes:

protocol_version_u32
chain_id_u32
height_u32
timestamp_u32
listening_port_u16

A v2 node must reject the old message. Do not add an auto-detection fallback: accepting an unnamespaced handshake reintroduces cross-network ambiguity.

All peers in one topology must use version 2 and the same chain ID/magic/genesis.

Narrow early-v2 location upgrade

The only in-directory storage compatibility path is for early clean-v2 blocks.db height locations that contain exactly four bytes: the block file number.

On first access, the current node:

1. recognizes the exact legacy entry size;
2. scans that one indexed block file;
3. derives version-1 file + offset + length locations;
4. upgrades all represented legacy entries in one database batch;
5. serves later reads from exact locations.

This is safe only because the surrounding v2 block serialization is unchanged. Unknown sizes/versions fail closed.

It does not convert prototype block bodies, accounts, chainstate, Redis, genesis, or P2P.

Explorer index upgrades

Explorer SQLite is a projection, so prefer rebuild over hand migration when schema or canonical identity is incompatible.

Before reusing a database, the index checks schema, network, chain ID, indexed height, and block identity. A wrong network is rejected. A diverged same-network prefix is rebuilt.

Safe manual rebuild:

1. stop the node;
2. move .sqlite3, -wal, and -shm together;
3. leave canonical data untouched;
4. start with --explorer-index;
5. wait for ready and verify indexed tip ID.

Do not write a SQLite schema migration that invents missing canonical facts. Recompute derived rows from blocks.

API compatibility

For private RPC and Explorer API version 1:

• adding optional response fields is normally client-compatible if clients ignore unknown fields;
• changing a field’s type, meaning, precision, or required presence can be breaking;
• removing/renaming routes or errors is breaking;
• changing decimal strings to JSON numbers is breaking and unsafe;
• reinterpreting ready, confirmations, or accepted is breaking even if JSON shapes remain;
• request bounds and pagination semantics are part of the contract.

Update OpenAPI, official clients, browser gateway validators, docs, and contract tests together.

Wallet-vault compatibility

Vault records declare:

{
  "version": 1,
  "kdf": "PBKDF2-SHA256",
  "iterations": 250000,
  "cipher": "AES-256-GCM"
}

The wallet validates version, algorithm names, KDF range, and required base64 fields before decryption. Unsupported records fail rather than being re-encrypted blindly.

For a future vault version:

1. keep the original ciphertext untouched until successful authenticated decryption;
2. verify recovered address/public key against derived secrets;
3. write the new record atomically where the platform permits;
4. retain rollback/recovery instructions;
5. never reduce KDF cost silently;
6. test wrong-password, truncated, corrupted-tag, and interrupted-write cases.

The mnemonic remains the primary portable recovery artifact.

Consensus-change procedure

A change to transaction bytes, address derivation, block preimage, validation, difficulty, subsidy, or genesis cannot be treated as an ordinary in-place software update.

Before release:

1. specify old and new rules unambiguously;
2. decide whether the change creates a clean chain/network ID or a height-activated transition;
3. define behavior for nodes before, at, and after activation;
4. update canonical vectors and negative fixtures;
5. implement all node/wallet/miner/explorer changes;
6. define storage/index rollback and reorg interaction;
7. run cross-version interoperability and partition tests;
8. publish an operator upgrade/rollback window;
9. prevent old software from silently joining the wrong network;
10. update this documentation in the same release.

For the alpha, a clean new testnet is safer than complex height activation unless compatibility is a deliberate research goal.

Pre-upgrade inventory

Record:

software commit/version
Python/Node versions
network + chain ID + magic
data directory
Redis host/port/DB
P2P/RPC/explorer/wallet ports
local tip height + ID
connected peer tips
wallet address + verified offline backup status
Explorer indexed height + ID
service-manager environment
reverse-proxy/frontend API origin

Never include mnemonic, private key, wallet password, RPC token, or vault plaintext in this inventory.

Post-upgrade verification

Check in order:

1. process starts without compatibility fallback warnings;
2. /health reports expected network/API;
3. authenticated /v1/status reports intended data directory and genesis/tip;
4. P2P handshakes only with version 2 same-chain peers;
5. Redis is available and isolated;
6. wallet derives the expected address and stays testnet-only;
7. explorer core routes match canonical block data;
8. SQLite reaches ready with matching indexed block ID;
9. static explorer points only to public /api/v1 origin;
10. one disposable end-to-end transfer can be admitted, relayed, mined, and confirmed in the controlled network.

Compare hashes, not only heights.

Rollback

Application rollback is safe only when the older build understands every data, wire, API, and consensus change made since its version.

When that is uncertain:

• stop the new process;
• preserve its data directory unchanged;
• restore the old binary with the old read-only directory and old isolated services;
• do not point an old binary at a directory already mutated by newer schemas;
• do not reconnect incompatible peers;
• document which network history each directory represents.

There is no supported general chain rollback or reindex command. A filesystem copy is not a substitute for a defined protocol rollback.

Mainnet migration

There is no mainnet migration because there is no current mainnet genesis. Any future mainnet launch must be a separately reviewed network definition, not a rename of educational testnet state.