Feat: fpc-fsc extension submodule

[PsychoPunkSage]

What this PR does / why we need it:

This PR migrates all FPC-related FSC (Fabric Smart Client) code out of the FSC repository and into FPC as a new extension/fsc submodule, resolving the cyclic dependency introduced by FSC importing parts of the FPC client SDK.

The changes include:

• New extension/fsc submodule: Hosts the FPC platform services (platform/fabric/services/fpc/) and NWO integration helpers (integration/nwo/fabric/fpc/, integration/nwo/fabric/topology/) previously living inside FSC.
• New echo integration test (integration/go_chaincode/echo/): End-to-end test that exercises the new extension submodule.
• Updated topology files: All topology.go files across auction, kv_test, simulation, IRB demo, and the simple testing network now import FPC topology helpers from extension/fsc instead of FSC internals. SDK import path updated from platform/fabric/sdk to platform/fabric/sdk/dig to align with post-PR-696 FSC structure.
• Updated test files: All integration test entrypoints now explicitly call ii.RegisterPlatformFactory(fpcnwo.NewPlatformFactory()) since FSC PR Go support #696 removed the built-in FPC platform registration from FSC.
• Updated view/client files: All FPC service imports redirected from fabric-smart-client/platform/fabric/services/fpc to extension/fsc/platform/fabric/services/fpc.
• Updated go.mod files: extension/fsc added as a direct dependency with local replace directives pointing to the post-PR-696 FSC clone until the upstream commit is available via a real pseudo-version.

After this PR, users who want to use FPC with FSC applications simply import FSC core + the extension/fsc submodule and wire it in via topology.go, no FPC code lives in FSC anymore.

Which issue(s) this PR fixes:
Fixes #784

Special notes for your reviewer:

• The companion change on the FSC side is hyperledger-labs/fabric-smart-client#696 (remove fpc). That PR is now merged and released as v0.11.0, all go.mod files in this PR reference the real upstream version; no local replace directives for FSC remain.
  • extension/fsc is a standalone Go module (go.mod at extension/fsc/go.mod) - Dependabot will not see it from the root. Keep this in mind for future dependency bumps.
  • The integration/go_chaincode/echo/ test is the primary validation path for this migration; it exercises the full extension wiring end-to-end.
  • go mod tidy on all affected modules auto-upgraded the Go toolchain requirement to 1.26.3 (minimum required by FSC v0.11.0).

How I tested:
Ran the echo FSC integration test from integration/go_chaincode/ with Fabric binaries (FAB_BINS) pointing to Fabric v3.1.4:

export FAB_BINS=<path-to-fabric-v3.1.4-binaries>
GOLANG_PROTOBUF_REGISTRATION_CONFLICT=warn go test -v -timeout 20m ./echo/...

Result:

Ran 2 of 2 Specs in 224.877 seconds
SUCCESS! -- 2 Passed | 0 Failed | 0 Pending | 0 Skipped
--- PASS: TestEndToEnd (224.88s)
ok  github.com/hyperledger/fabric-private-chaincode/integration/go_chaincode/echo  224.970s

Does this PR introduce a user-facing changes and/or breaks backward compatability?:

Yes. Any user currently using FPC with FSC must update their code:

1. Import paths - FPC service and topology helpers have moved out
   of FSC:

   Old (FSC)	New (extension/fsc)
   github.com/hyperledger-labs/fabric-smart-client/platform/fabric/services/fpc	github.com/hyperledger/fabric-private-chaincode/extension/fsc/platform/fabric/services/fpc
   github.com/hyperledger-labs/fabric-smart-client/integration/nwo/fabric/topology (FPC helpers)	github.com/hyperledger/fabric-private-chaincode/extension/fsc/integration/nwo/fabric/topology
   github.com/hyperledger-labs/fabric-smart-client/platform/fabric/sdk	github.com/hyperledger-labs/fabric-smart-client/platform/fabric/sdk/dig

2. New dependency - Add extension/fsc to your go.mod: require github.com/hyperledger/fabric-private-chaincode/extension/fsc v

3. Platform factory registration - Tests must now explicitly register the FPC platform factory (previously done implicitly by FSC):

ii.RegisterPlatformFactory(fpcnwo.NewPlatformFactory())

where fpcnwo is: import fpcnwo "github.com/hyperledger/fabric-private-chaincode/extension/fsc/integration/nwo/fabric/fpc"

[PsychoPunkSage]

Addressing the protobuf namespace conflict (rwset.TxReadWriteSet already registered) #958

The CI failure in the IRB and echo integration tests is caused by a protobuf namespace conflict. Two packages define the same proto message types and end up in the same binary:

• [email protected]: pulled in by FPC's client_sdk -> internal/utils (old API)
• fabric-protos-go-apiv2: pulled in by FSC v0.11.0 (new API)

Added GOLANG_PROTOBUF_REGISTRATION_CONFLICT=warn to the go test invocations in integration/go_chaincode/echo/Makefile and samples/demos/irb/Makefile. This is the officially documented bridge (https://protobuf.dev/reference/go/faq#namespace-conflict) from the Go protobuf team for exactly this migration scenario - it keeps the first registration and suppresses the panic.

[PsychoPunkSage]

CI Failure: Orderer Config Incompatibility (FSC v0.11.0 ↔ Fabric 2.5.9)

The IRB demo integration test panics during orderer startup: failed to parse config: Error unmarshalling config into struct: 1 error(s) decoding:

• 'General' has invalid keys: Backoff, Throttling panic: Timed out after 60.000s.

Root cause

FSC v0.11.0 generates orderer config via its NWO template (integration/nwo/fabric/topology/orderer_template.go) which includes two keys under General:

General:
  Throttling:
    Rate: 0
    InactivityTimeout: 5s
  Backoff:
    BaseDelay: 1s
    Multiplier: 1.6
    MaxDelay: 2m

These keys were introduced for Fabric v3.x. FPC's CI currently pins to Fabric 2.5.9 (config.mk, utils/docker/dev/Dockerfile) which does not recognize them -> causing the orderer to refuse startup.

Why we can't just pin FSC to an older version
FSC PR #696 (hyperledger-labs/fabric-smart-client#696) (which removed FPC code from FSC — the change this PR receives on the FPC side) landed in FSC v0.11.0. There is no FSC version that is both:

• ✅ After PR Go support #696 (FPC code removed from FSC)
• ✅ Compatible with Fabric 2.5.9 orderer config

They came together. Pinning to an older FSC means shipping an integration against a version where FSC still contains FPC internals - defeating the purpose of this PR.

Fix required

Upgrade FPC's pinned Fabric binary from 2.5.9 → 3.1.4 in:

• config.mk (FABRIC_VERSION)
• utils/docker/dev/Dockerfile
• utils/docker/dev_peer_cc-builder/Dockerfile

The echo integration test was already validated locally against Fabric 3.1.4:

Ran 2 of 2 Specs in 224.877 seconds
  SUCCESS! -- 2 Passed | 0 Failed | 0 Pending | 0 Skipped

This upgrade is the correct long-term move to align FPC with FSC v0.11.0+, but since it touches all of FPC's CI (not just the new tests), it warrants a deliberate review decision. Happy to include it in this PR or track it as a follow-up looking for guidance.

[mbrandenburger]

Thank you @PsychoPunkSage for working on this! This is a great step forward! I left you a few comments; Please have a look.

[mbrandenburger]

I am wondering if we can re-compile the protos with the new protobuf. WDYT?

[PsychoPunkSage]

Well the comment seems to be wrong,
I just checked internal/protos/fpc.pb.go and fabric-protos-go-apiv2's generated files, and both are already generated by the modern protoc-gen-go

[PsychoPunkSage]

Hi @mbrandenburger,
I have found a hard blocker

Recreate:

make all

confidential-escrow sample cannot build on fabric-chaincode-go/v2 - blocked on cc-tools

flagging a build break in samples/chaincode/confidential-escrow surfaced by the fabric-chaincode-go v1 -> v2 migration in this branch.

Error

chaincode/escrow.go:60:14: cannot use err.GetErrorResponse() (value of struct type "github.com/hyperledger/fabric-protos-go/peer".Response) as "github.com/hyperledger/fabric-protos-go-apiv2/peer".Response value in assignment
chaincode/escrow.go:99:24: cannot use stub (variable of interface type "github.com/hyperledger/fabric-chaincode-go/v2/shim".ChaincodeStubInterface) as "github.com/hyperledger/fabric-chaincode-go/shim".ChaincodeStubInterface value in argument to tx.Run: ...

Root cause

confidential-escrow depends on github.com/hyperledger-labs/cc-tools (currently pinned at v1.0.2). cc-tools's tx.Run(...) and TxError.GetErrorResponse() are typed against the old, pre-v2 Fabric packages:

• github.com/hyperledger/fabric-chaincode-go/shim (not /v2)
• github.com/hyperledger/fabric-protos-go/peer (not -apiv2)

I checked all published cc-tools tags (up to the latest, v1.0.3) and its go.mod still pins:

github.com/hyperledger/fabric-chaincode-go v0.0.0-20210603161043-af0e3898842a
github.com/hyperledger/fabric-protos-go    v0.0.0-20210528200356-82833ecdac31

i.e. no cc-tools release supports fabric-chaincode-go/v2 / fabric-protos-go-apiv2. This isn't fixable by editing local call sites in escrow.go/server.go — the mismatch is inside cc-tools itself.

What I'm asking

Since this isn't fixable within this repo alone, how would you like to proceed:

1. Skip/exclude confidential-escrow from the v2 migration for now and track it as a follow-up once cc-tools ships v2 support, or
2. Fork/patch cc-tools locally to retarget /v2 + -apiv2, or
3. Something else you'd prefer.

Happy to open an upstream issue against cc-tools if that's useful.

[mbrandenburger]

What I'm asking

Since this isn't fixable within this repo alone, how would you like to proceed:

1. Skip/exclude confidential-escrow from the v2 migration for now and track it as a follow-up once cc-tools ships v2 support, or
2. Fork/patch cc-tools locally to retarget /v2 + -apiv2, or
3. Something else you'd prefer.

Happy to open an upstream issue against cc-tools if that's useful.

@samuelvenzi would it be reasonable to update cc-tools to the v2 API?

[samuelvenzi]

@samuelvenzi would it be reasonable to update cc-tools to the v2 API?

Yes, I think so. I would only need to know whether this breaks deployments in older Fabric versions such as v2.2.

@PsychoPunkSage Can you maybe investigate that?

[PsychoPunkSage]

@PsychoPunkSage Can you maybe investigate that?

hi @samuelvenzi
here is what i found:

Wire format check (i.e. diff between fabric-protos-go and fabric-protos-go-apiv2)

• Compared the ChaincodeMessage.Type enum between the two proto libraries. fabric-protos-go v0.0.0-20210528200356 (what cc-tools pins) vs fabric-protos-go-apiv2 v0.3.7 (what the v2 migration uses):

> 23: "PURGE_PRIVATE_DATA"
> 24: "WRITE_BATCH_STATE"
> 25: "GET_STATE_MULTIPLE"

Values 0–22 are identical i.e. same names, same numbers, no renumbering or removals. So, -apiv2 produces byte-identical messages to -go for every type that existed before

---

Does the v2 shim actually emit the new message types?

Checked fabric-chaincode-go/[email protected] (what the migration uses). All three of the new types are gated:

• PURGE_PRIVATE_DATA (23) and GET_STATE_MULTIPLE (25) >> sent only from stub.PurgePrivateData() / stub.GetMultipleStates(). Opt-in; not emitted unless chaincode calls them.
• WRITE_BATCH_STATE (24) >> negotiated with the peer, not assumed. On REGISTERED, the shim unmarshals ChaincodeAdditionalParams from the peer's payload (handler.go:801-811) and sets usePeerWriteBatch = ccAdditionalParams.UseWriteBatch. A v2.2 peer predates this field, so it replies with an empty payload and UseWriteBatch defaults to false i.e. the batching branch never runs, so, writes go out as ordinary PUT_STATE. The unconditional FinishWriteBatch() calls are no-ops with an empty buffer.

So old-peer compatibility is a deliberate, tested design guarantee in the shim.

---

Which v2 shim APIs require a peer newer than 2.2?

Diffed the ChaincodeStubInterface method set between [email protected] (what cc-tools pins) and [email protected]. Six additions:

Safe on Fabric 2.2:

• GetAllStatesCompositeKeyWithPagination >> convenience wrapper; delegates to handleGetStateByRange, i.e. message GET_STATE_BY_RANGE (14), which has existed since 1.x. New API, old wire.
• StartWriteBatch / FinishWriteBatch >> gated by the peer-negotiated usePeerWriteBatch flag; no-ops against an old peer.

Require a newer peer (must not be called):

• PurgePrivateData >> PURGE_PRIVATE_DATA (23), Fabric 2.5+
• GetMultipleStates >> GET_STATE_MULTIPLE (25), Fabric 3.0
• GetMultiplePrivateData >> same message 25

No methods were removed, so nothing in cc-tools loses an API it depends on.

Separately, several signatures changed shape, not just import path, e.g. Init/Invoke/InvokeChaincode now return *peer.Response instead of pb.Response by value, and GetTxTimestamp returns *timestamppb.Timestamp. That's the source of the original build error.

---

Call sites:

Moving cc-tools + confidential-escrow to fabric-chaincode-go/v2 + fabric-protos-go-apiv2 should not break Fabric 2.2 deployments:

1. Enum values 0–22 are identical across both proto libraries >> same numbers, so byte-identical wire encoding. The v1->v2 change is Go codegen, not protocol.
2. The three new message types are all gated: two behind opt-in stub methods, one behind peer-negotiated capability that defaults off.
3. Of the six new interface methods, only three carry a newer-peer requirement.
4. Neither codebase calls any of them outside mocks.

The caveat that bounds this: the conclusion holds as long as we don't start calling PurgePrivateData, GetMultipleStates, or GetMultiplePrivateData in production paths.

---

Conclusion:

I believe migrating cc-tools to fabric-chaincode-go/v2 + fabric-protos-go-apiv2 does not break Fabric 2.2 at the protocol level, and does not affect existing v1 users if released as cc-tools/v2.

cc @mbrandenburger