Skip to content

v0.8.0-migration-guide.md

Latest commit

 

History

History
144 lines (98 loc) · 4.29 KB

v0.8.0-migration-guide.md

File metadata and controls

144 lines (98 loc) · 4.29 KB

v0.8.0 Migration Guide

This guide covers upgrading a Fiber node from v0.7.x to v0.8.0.

Unlike the v0.7.0 migration (which required closing all channels and starting fresh), v0.8.0 supports in-place data migration. The fnn-migrate tool will update your existing database without losing channel state or funds.

Prerequisites

  • Fiber node is running v0.7.0 or v0.7.1
  • Node is stopped (not running)
  • A recent backup of your data directory (see the backup guide)

Step 1: Stop the node

# Find the running process
ps aux | grep fnn

# Terminate it (replace PID with your process ID)
kill <PID>

Step 2: Back up your data directory

Always create a backup before migrating:

tar -zcvf backup-fiber-dir.tar.gz fiber-dir

Step 3: Build or download v0.8.0

Build from source:

git checkout v0.8.0
cargo build --release -p fnn
cargo build --release --manifest-path migrate/Cargo.toml

Or download the pre-built binaries from the releases page.

Step 4: Run the migration tool

./fnn-migrate -d /path/to/fiber-dir

The -d / --dir flag takes the Fiber data directory (same as fnn -d). The tool opens the RocksDB store at <dir>/store automatically.

The tool applies all pending migrations in order. You will see log output for each migration step:

Migration What it does
Channel actor state (prefix 0) Appends new pending_replay_updates and last_was_revoke fields with default values
Channel-by-pubkey index (prefix 64) Re-keys the channel index from PeerId to Pubkey
Network actor state (prefix 16) Clears legacy PeerId-keyed network state (rebuilt on next start)
Channel open records (prefix 201) Deletes ephemeral channel-opening status records (rebuilt if needed)

The migration is idempotent — running it again on an already-migrated database is safe and will be a no-op.

Step 5: Update your configuration

No configuration file changes are required for v0.8.0.

Step 6: Start the node

./fnn -c /path/to/fiber-dir/config.yml -d /path/to/fiber-dir

On first start after migration the node will:

  • Rebuild the network peer address map from gossip
  • Re-establish connections with known peers
  • Resume any in-flight payments

RPC client changes

v0.8.0 introduces several RPC breaking changes. If you have scripts or integrations that call the Fiber RPC, update them for the following:

PeerId → Pubkey

All peer_id parameters and response fields have been replaced with pubkey. PeerIds were base58-encoded libp2p identifiers; Pubkeys are hex-encoded compressed secp256k1 public keys (66 hex characters).

Before (v0.7.x):

{"method": "open_channel", "params": [{"peer_id": "QmXxx..."}]}

After (v0.8.0):

{"method": "open_channel", "params": [{"pubkey": "02abc..."}]}

Affected RPCs: open_channel, list_channels, connect_peer, disconnect_peer, node_info.

JSON serialization changes

  • Attribute enum variants are now snake_case: FinalHtlcTimeout → final_htlc_timeout
  • HashAlgorithm variants are now snake_case: CkbHash → ckb_hash
  • CkbInvoice.signature is now a hex string instead of a structured object
  • ChannelState flags format: "OUR_INIT_SENT | THEIR_INIT_SENT" (SCREAMING_SNAKE_CASE with pipes)
  • CCH invoice variants now carry encoded invoice strings instead of structured objects

CCH order status renames

  • Succeeded → Success
  • OutgoingSucceeded → OutgoingSuccess

Error behavior

connect_peer and disconnect_peer now return proper RPC errors on failure instead of silently returning success.

Troubleshooting

Migration fails with "unexpected end of file"

This usually means the database was written by a version newer than v0.7.x. Verify you're migrating from v0.7.0 or v0.7.1.

Node fails to start after migration

  1. Check the error message in the logs
  2. Restore from backup: tar -xzf backup-fiber-dir.tar.gz
  3. Re-run the migration tool
  4. If the problem persists, open an issue at https://github.com/nervosnetwork/fiber/issues

Channels show as disconnected after upgrade

This is expected. The node will automatically reconnect to peers and re-establish channels. Allow a few minutes for the network to stabilize.