Skip to content

feat: add Fabric snapshot to Fabric X migration RFC - #68

Open
syndbg wants to merge 1 commit into
hyperledger:mainfrom
syndbg:feat-add-fabric-to-fabric-x-migration
Open

feat: add Fabric snapshot to Fabric X migration RFC#68
syndbg wants to merge 1 commit into
hyperledger:mainfrom
syndbg:feat-add-fabric-to-fabric-x-migration

Conversation

@syndbg

@syndbg syndbg commented Aug 9, 2026

Copy link
Copy Markdown

Description

This RFC defines an offline migration from a Fabric Classic peer snapshot to
Fabric-X.

It specifies:

  • validation of the source snapshot and deterministic genesis-data bundle;
  • one Fabric channel per Fabric-X network, with mapped application namespaces;
  • migration of public state and transaction IDs for anti-replay;
  • explicit recording of PDC exclusions (hashes) without exposing private values or
    hashes as public state;
  • atomic committer bootstrap at target anchor B; and
  • verification, idempotency, activation, multi-organization agreement, and
    recovery.

Source block history, online migration, PDC values, automatic chaincode
translation, and channel consolidation are outside this proposal.

Proof of concept

Related issues

cc @liran-funaro @cendhu @tock-ibm

Signed-off-by: Anton Antonov <anton.synd.antonov@gmail.com>
@syndbg
syndbg force-pushed the feat-add-fabric-to-fabric-x-migration branch from c0a568a to 9ee3afa Compare August 9, 2026 23:06
@syndbg

syndbg commented Aug 9, 2026

Copy link
Copy Markdown
Author

PoC testing coverage

The migration integration test uses the exporter and disposable Fabric and Fabric-X networks. The primary path:

  1. creates the Fabric-X network and target namespace;
  2. records and freezes the target at anchor B;
  3. exports and imports the genesis-data file;
  4. verifies the imported state, transaction IDs, target configuration, namespace map, installed policy, and migration record;
  5. activates the migration and restarts Fabric-X services; and
  6. submits a normal transaction through the orderer and confirms that it updates an imported key from version 0.

The integration scenarios cover:

  • Fabric 2.5.16 and Fabric 3.1.5 LevelDB snapshots;
  • a Fabric 3.1.5 CouchDB snapshot;
  • retrying the same bundle without importing its rows again;
  • rejecting imports after activation;
  • two source channels migrated into separate Fabric-X networks;
  • two committer organizations importing the same bundle, reporting identical verification results, and committing the same later transaction; and
  • reconstructing an empty committer database by processing Fabric-X blocks through B, reapplying the same bundle, and then processing the later Fabric-X blocks.

The rebuild scenario reuses the original bundle. It does not test whether a replacement bundle is rejected after the database-local migration record has been lost.

The committer bootstrap tests cover the failure paths separately: atomic rollback, missing or non-empty namespaces, existing transaction IDs, missing block 0, unsupported target policies, changed state or policy bindings, changed anchors, and attempts to use a different bundle while the migration record exists.

Run the focused tests with:

go test ./cmd/committer ./service/vc
go test -tags=integration ./integration/migration \
  -run TestInitFromSnapshot \
  -count=1 -v

@syndbg
syndbg marked this pull request as ready for review August 17, 2026 12:36
Comment on lines +852 to +858
## Omit Fabric transaction IDs

Rejected because a transaction committed before `H` could be submitted to the
target again. Version `1` imports the IDs into `migrated_tx_ids`, and normal
duplicate detection checks that immutable registry together with `tx_status`.
The importer does not invent Fabric-X status or height values for source
transactions.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On a second note, not needed since they'll be rejected. To be removed from the snapshot and import.
Extra point - have an integration test verify this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant