hyperledger / hyperledger/fabric-x

POC: Validate deterministic channel-to-namespace mapping for Fabric → Fabric-X ledger migration

Open
#226 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
64
Forks
80
Avg merge
1d 22h
Merged PRs (30d)
15

Description

### Summary

This issue proposes a focused proof-of-concept (POC) to validate one of the core transformation steps in the LFDT migration pipeline: converting Fabric’s **channel-based state organization** into Fabric-X’s **namespace-based model**.

The objective is to isolate and validate the correctness, determinism, and edge-case behavior of the channel-to-namespace mapping before integrating it into the full exporter pipeline.

---

### Background & Motivation

Hyperledger Fabric organizes ledger state as:

* Channel → Namespace → Key-Value

Whereas Fabric-X operates on:

* Namespace → Key-Value

This structural mismatch introduces a critical requirement during migration: defining a mapping strategy that:

* Preserves data integrity
* Avoids namespace collisions
* Produces deterministic and reproducible output
* Remains simple and consistent with Fabric-X design principles

Given that this mapping is foundational to the migration pipeline, validating it independently can help reduce complexity and risk before full pipeline integration.

---

### Problem Focus

The mapping step must address:

1. **Deterministic namespace transformation**

* Same input must always produce identical output

2. **Collision avoidance**

* Different `(channel, namespace)` pairs should not produce conflicting Fabric-X namespaces

3. **Preservation of key-value integrity**

* No keys should be lost or duplicated during transformation

4. **Simplicity vs correctness trade-off**

* Mapping strategy should remain predictable without introducing unnecessary complexity

---

### Scope (Intentionally Minimal)

This POC focuses only on validating mapping correctness:

* Define a simplified snapshot representation (mock or extracted structure)
* Implement transformation:

* `(channel + namespace) → Fabric-X namespace`
* Output a JSON representation of transformed state
* Perform basic validation:

* key count consistency
* collision detection
* deterministic output

Example:

Input:

```id="zqk91w"
Channel: mychannel
Namespace: asset
Keys: [asset1, asset2]
```

Output:

```id="3gq1as"
Namespace: mychannel.asset
Keys: [asset1, asset2]
```

---

### What This POC Does NOT Cover

To keep the scope focused, this POC intentionally excludes:

* Full Fabric snapshot parsing
* Exporter CLI or binary genesis format
* Version conversion logic
* Private Data Collection (PDC) handling
* Bootstrap integration into Fabric-X

These aspects can be explored in later stages once mapping behavior is validated.

---

### Expected Outcomes

* A clear and minimal mapping strategy
* Identification of potential edge cases (e.g., collisions, naming ambiguity)
* Validation that mapping preserves state integrity
* A reference implementation that can guide exporter design

---

### Relation to Ongoing Work

There is ongoing work on a full exporter pipeline (`tools/fxmigrate`).
This POC complements that effort by isolating and validating the **mapping logic independently**, allowing clearer reasoning about correctness before integrating into a larger system.

---

### Proposed Approach

1. Define a simplified snapshot structure
2. Implement mapping function
3. Generate transformed output
4. Validate:

* key preservation
* collision handling
* deterministic behavior

---

### Potential Extensions (Future Work)

* Extend mapping strategy for edge cases
* Explore treatment of PDC-related artifacts
* Validate mapping against real snapshot data
* Integrate with exporter pipeline

---

### Why This Matters

This mapping step is a foundational transformation in the migration pipeline.
Validating it early helps:

* reduce complexity in downstream components
* ensure correctness before scaling implementation
* provide clarity for design decisions in exporter and bootstrap stages

---

I’d be happy to start with a minimal implementation and iterate based on feedback.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.