feat(fxmigrate): scaffold Exporter CLI for Fabric to Fabric-X state migration

[sridhar-panigrahi]

This adds tools/fxmigrate — the Exporter CLI that handles the export side of the Fabric → Fabric-X migration pipeline from RFC hyperledger/fabric-x-rfcs#5 and epic #21.

The tool reads a standard Fabric peer snapshot directory, filters out everything that doesn't belong in Fabric-X (PDC hashes, system chaincodes, implicit org collections), converts Fabric version pairs to Fabric-X scalar integers, and writes a genesis-data file that the committer's --init-from-snapshot bootstrap mode can ingest.

Structure

Follows the same layout as fxconfig — cobra CLI, internal packages, unit tests:

tools/fxmigrate/
  main.go
  internal/
    cli/v1/
      root.go       cobra root: export / verify / version subcommands
      export.go     5-phase export flow
      verify.go     placeholder — post-migration verifier is a follow-up PR
      version.go
    snapshot/
      manifest.go   reads _snapshot_signable_metadata.json, recomputes SHA-256 checksums
      reader.go     streaming binary parser for public_state.data
      filter.go     namespace and key filtering rules
    genesis/
      writer.go     length-delimited binary output with JSON header

What the export command does

fxmigrate export \
  --snapshot ./peer/snapshots/completed/mychannel/100 \
  --channel  mychannel \
  --namespace token \
  --output   genesis.bin

Five phases:

1. Read _snapshot_signable_metadata.json and verify SHA-256 checksums for all snapshot files
2. Scan public_state.data to discover which namespaces are present
3. Stream all key-value pairs through the filter (drops PDC, system chaincodes, CouchDB internals)
4. Write the genesis-data file — length-delimited binary with a JSON header containing namespace, source channel, block height, entry count, and export timestamp
5. Print SHA-256 of the output file

Filtering

Per RFC §3.1, excluded from migration:

• System chaincodes: lscc, _lifecycle, cscc, qscc, escc, vscc
• PDC hash namespaces ($$h$$ pattern) and PDC private state ($$p$$ pattern)
• Implicit org collections (any namespace containing $$)
• CouchDB internal metadata keys (\x00collection prefix)

Version conversion

Fabric stores versions as (blockNum, txNum) pairs. Converted to Fabric-X scalar BIGINT: (blockNum << 32) | txNum

Tests

5 unit tests: manifest parsing (happy path, missing file, empty channel name), namespace filtering, key filtering.

Related

• RFC: Proposal: Fabric to Fabric-X state migration fabric-x-rfcs#5
• Epic: Define Data Migration Path from Hyperledger Fabric Snapshot to Fabric-X #21
• Committer StateImporter PoC: feat(vc): add StateImporter for bulk state initialization from external sources fabric-x-committer#516

Signed-off-by: Shridhar Panigrahi sridharpanigrahi2006@gmail.com

[sridhar-panigrahi]

@cendhu — this is the Exporter CLI piece from the RFC. Adds tools/fxmigrate with the snapshot manifest verification, PDC filtering, version conversion, and the 5-phase export flow. Still need to add tests for reader.go (needs a real snapshot fixture) and wire up the --init-from-snapshot path on the committer side, but wanted to get eyes on the structure first. Let me know if anything looks off.