feat: add chaincode-to-fsc asset transfer POC example by aaradhychinche-alt · Pull Request #1304 · hyperledger-labs/fabric-smart-client

aaradhychinche-alt · 2026-04-25T14:51:39Z

Summary

This PR adds a minimal example demonstrating how a classic Fabric chaincode use case (asset transfer) can be implemented using a Fabric Smart Client (FSC)-style flow.

Motivation

This example aims to help developers understand how to move business logic from on-ledger chaincode execution to client-side flow orchestration using FSC.

What’s Included

CLI-based example (cmd/token-transfer)
Flow implementation (internal/flow)
Mock protocol layer (internal/protocol)
Simple asset model (internal/model)

Flow

The example demonstrates:

reading state
validating input
preparing and “endorsing” a transaction
submitting the transaction
verifying committed state

Scope

single asset transfer
single organization
mocked backend (in-memory)

Notes

intentionally minimal to focus on flow structure
no changes to core FSC components
designed as a tutorial-style example under examples/

Future Work

integrate real FSC components
extend to multi-org flows
expand asset lifecycle
POC: Porting Fabric Chaincode (Asset Transfer) to Fabric Smart Client Flow (Tutorial Example) #1303

Copilot

Pull request overview

Adds a minimal “chaincode-to-FSC” tutorial example that demonstrates an asset transfer flow implemented as client-side orchestration (mocked, in-memory backend), intended to help developers map chaincode patterns to FSC-style flows.

Changes:

Introduces an in-memory mock “protocol” layer for asset state read/write.
Adds a simple transfer flow with input validation, submit, and verification steps.
Adds a CLI entrypoint and accompanying tutorial documentation for running the example.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
examples/chaincode-to-fsc/internal/protocol/fabricx.go	In-memory mock ledger/protocol for reading assets and submitting transfers
examples/chaincode-to-fsc/internal/model/asset.go	Minimal asset data model
examples/chaincode-to-fsc/internal/flow/transfer_asset.go	Transfer flow orchestration (read → validate → submit → verify)
examples/chaincode-to-fsc/cmd/token-transfer/main.go	CLI for invoking the transfer flow
examples/chaincode-to-fsc/go.mod	Standalone Go module for the example
examples/chaincode-to-fsc/READEME.md	Tutorial-style documentation for running the example

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-25T14:54:30Z

+endorsing transaction
+submitting transaction
+verifying state
+transfer successful: a1 -> bob


The documented output doesn't match what the code prints/returns. TransferAsset returns "success: asset %s now owned by %s", but the README shows "transfer successful: a1 -> bob". Please update the README output (or adjust the program output) so users can follow the tutorial without confusion.

Suggested change

transfer successful: a1 -> bob

success: asset a1 now owned by bob

Copilot · 2026-04-25T14:54:30Z

+module github.com/hyperledger-labs/fabric-smart-client/examples/chaincode-to-fsc
+
+go 1.25.7


This example introduces a nested Go module, but the repo's make tidy target only runs go mod tidy in a few locations and currently won't tidy this module. Consider updating the repo tooling (or adding a note in the README) so future dependency changes here don't get missed.

Copilot · 2026-04-25T14:54:30Z

+var assets = map[string]model.Asset{
+	"a1": {
+		ID:    "a1",
+		Owner: "alice",
+	},
+}


assets is a package-level map that is read and written by GetAsset/SubmitTransfer without any synchronization. If this example is invoked concurrently (or exercised under -race), this can trigger data races and even runtime panics on concurrent map access. Consider guarding the map with a sync.RWMutex (or encapsulating state in a struct) and using the lock in both functions.

mbrandenburger · 2026-04-29T14:39:18Z

Thank you @aaradhychinche-alt for creating this PR. I've left you a few comments on the corresponding issue. I've changed this PR to draft mode for now - so we can refine it more and more :D

aaradhychinche-alt · 2026-04-29T15:05:20Z

Thank you @aaradhychinche-alt for creating this PR. I've left you a few comments on the corresponding issue. I've changed this PR to draft mode for now - so we can refine it more and more :D

thankssssss i will look upto the reviews

aaradhychinche-alt · 2026-05-01T12:26:17Z

@mbrandenburger i have updated the pr :-

Added topology and flow explanation in the README
Aligned the API with asset-transfer (ReadAsset, TransferAsset)
Cleaned up the execution output and kept phase context inline
Clarified that roles (client/endorser) are simulated but map to real FSC nodes
should i now move this toward a real FSC + Fabric-X network setup next and make this poc a prototype ??
can u have a review on the changes please ?

aaradhychinche-alt · 2026-05-04T10:36:06Z

@mbrandenburger What should we do next to improve this ?

mbrandenburger · 2026-05-05T07:37:50Z

Hi @aaradhychinche-alt Thank for working on this - a good step forward. You should move forward with this and start porting the Asset Transfer logic into views; setup fsc nodes nodes; think about how to spinnup a fabric-x network (for example, you could use our integration test suite (nwo)).

aaradhychinche-alt · 2026-05-08T10:54:33Z

Hi @marcus Brandenburger I’ve updated the PR with a working chaincode-to-FSC migration PoC.
Key additions:
Ported chaincode logic into FSC views
Set up a real FSC network using NWO
Implemented endorsement via FSC sessions
Integrated Fabric-X ordering and finality
Added determinism checks and post-commit verification
Included end-to-end integration tests

Would appreciate it if you could take a look and share your feedback.

Signed-off-by: Aaradhy Chinche <aaradhychinche@gmail.com>

aaradhychinche-alt · 2026-05-12T02:40:49Z

@mbrandenburger what is your review ?

github-actions · 2026-05-18T00:44:01Z

👋 Hey @aaradhychinche-alt! This PR has been inactive for 5 days.

Are you still working on this? We will close this in 2 days if we see no further activity.

If you're still on it, leave a comment to let us know! If you'd like to step down, comment /unassign.

github-actions · 2026-05-18T04:34:43Z

Hey @aaradhychinche-alt 👋 thanks for the PR!
I'm your friendly PR Helper Bot 🤖 and I'll be riding shotgun on this one, keeping track of your PR's status to help you get it approved and merged.

This comment updates automatically as you push changes -- think of it as your PR's live scoreboard!
Here's the latest:

PR Checks

✅ DCO Sign-off -- All commits have valid sign-offs. Nice work!

❌ GPG Signature -- Heads up! The following commits don't have a verified GPG signature:

0903c24 feat: add chaincode-to-fsc asset transfer POC example

You'll need to sign your commits with GPG (e.g. git commit -S). See the Signing Guide for a step-by-step walkthrough.

✅ Merge Conflicts -- No merge conflicts detected. Smooth sailing!

❌ Issue Link -- Almost there! You are not assigned to the following linked issues: #1303.

Please ensure you are assigned to all linked issues before opening a PR. You can comment /assign on the issue to grab it!

⏳ All checks must pass before this PR can be reviewed. You've got this!

aaradhychinche-alt · 2026-05-18T04:44:29Z

👋 Hey @aaradhychinche-alt! This PR has been inactive for 5 days.

Are you still working on this? We will close this in 2 days if we see no further activity.

If you're still on it, leave a comment to let us know! If you'd like to step down, comment /unassign.

i am working on it!!

mbrandenburger

Thank you @aaradhychinche-alt for this work. Really good progress. I have a few suggestions below.

mbrandenburger · 2026-05-20T06:38:21Z

+| `issuer`   | Org1 | Initiator for `InitLedger` and `CreateAsset`.                  |
+| `endorser` | Org1 | Approver. Holds the chaincode-equivalent validation logic.     |
+| `auditor`  | Org1 | Witness responder on every state-changing transaction.         |


I believe we should merge issuer, endorser, auditor into a single node and call it endorser? This would simplify the topology a lot.

Optionally, we should have a second endorser in a different org to make a stronger policy.

mbrandenburger · 2026-05-20T06:45:54Z

+Prerequisites — match the Fabric-X compatibility matrix at the time of
+writing:
+
+| Tool                | Version          |
+| ------------------- | ---------------- |
+| Go                  | 1.26+            |
+| Docker              | 20.x+            |
+| Fabric-X-Orderer    | v0.0.21 / v0.0.23 |
+| Fabric-X-Committer  | v0.1.7  / v0.1.9 |


I suggest to remove this from this tutorial and refer to the FSC documentation.

Let's also link to the documentation how to setup the dev environment.

mbrandenburger · 2026-05-20T06:47:57Z

+### 8.1 Why a separate auditor node
+
+Classical chaincode applications often retrofitted an auditor by
+emitting chaincode events and scraping them off-chain. With FSC the
+auditor becomes a topology-level role — register an FSC node, hand it
+`AuditorView` as a responder, and every state-changing transaction
+automatically pulls the auditor into the endorsement flow. We did this
+to demonstrate the pattern; the example would still work without it.


As suggested earlier - I believe the auditor make this tutorial harder to follow.

mbrandenburger · 2026-05-20T06:50:22Z

+- **Second demo (work-in-progress).** A port of
+  `asset-transfer-private-data` that exercises the
+  hash-on-ledger / body-via-P2P pattern from §9.4.
+- **CC-Tools port (stretch).** Show that the methodology generalises
+  beyond hand-written chaincode.
+- **Index-key range scan helper (stretch).** A reusable FSC view that
+  implements the index-key pattern from §9.1, so applications get a
+  drop-in substitute for `GetStateByRange`.
+- **Blog post.** A 1500–2500-word digest of this README aimed at the
+  LFDT community.
+- **Meetup talk.** A 15-minute walkthrough with slides.
+
+Issues and PRs welcome. The mentorship project that produced this
+example is tracked in
+[LF-Decentralized-Trust-Mentorships/mentorship-program#59](https://github.com/LF-Decentralized-Trust-Mentorships/mentorship-program/issues/59).


Let's remove this section.

mbrandenburger · 2026-05-20T06:54:13Z

+This is the long-form companion to [README.md](README.md). The README is
+the tutorial a reviewer reads in 20 minutes; this file is the *textbook*
+that teaches you, line by line, what every piece of this PoC is doing
+and why. If you have never used FSC before, start here.


I think the detail in the walkthrough is great but I believe we should focus on a single documentation per tutorial. I suggest to remove the walkthrough. This also help to maintain the tutorial in the future.

mbrandenburger · 2026-05-20T07:03:13Z

@@ -0,0 +1,80 @@
+# Chaincode -> FSC Example (Asset Transfer)


We can remove examples/chaincode-to-fsc as now integration/fabricx/chaincode-to-fsc contains the real tutorial.

aaradhychinche-alt · 2026-05-20T07:23:05Z

@mbrandenburger thanks for the response i will look upto changes and apply them now

Copilot AI review requested due to automatic review settings April 25, 2026 14:51

Copilot started reviewing on behalf of aaradhychinche-alt April 25, 2026 14:52 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

mbrandenburger marked this pull request as draft April 29, 2026 14:37

mbrandenburger linked an issue Apr 29, 2026 that may be closed by this pull request

POC: Porting Fabric Chaincode (Asset Transfer) to Fabric Smart Client Flow (Tutorial Example) #1303

Open

mbrandenburger assigned aaradhychinche-alt May 1, 2026

aaradhychinche-alt force-pushed the poc/chaincode-to-fsc branch from d8dbfc3 to cc8a035 Compare May 8, 2026 16:42

feat: add chaincode-to-fsc asset transfer POC example

0903c24

Signed-off-by: Aaradhy Chinche <aaradhychinche@gmail.com>

aaradhychinche-alt force-pushed the poc/chaincode-to-fsc branch from 44f023c to 0903c24 Compare May 8, 2026 20:27

Merge branch 'main' into poc/chaincode-to-fsc

1f01ec9

aaradhychinche-alt marked this pull request as ready for review May 18, 2026 04:34

github-actions Bot added the status: needs revision The pull request requires changes from the author before it can be reviewed or merged label May 18, 2026

aaradhychinche-alt marked this pull request as draft May 18, 2026 04:35

Merge branch 'hyperledger-labs:main' into poc/chaincode-to-fsc

7ec663a

mbrandenburger requested changes May 20, 2026

View reviewed changes

	transfer successful: a1 -> bob
	success: asset a1 now owned by bob

		module github.com/hyperledger-labs/fabric-smart-client/examples/chaincode-to-fsc

		go 1.25.7 No newline at end of file

Conversation

aaradhychinche-alt commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

What’s Included

Flow

Scope

Notes

Future Work

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

mbrandenburger commented Apr 29, 2026

Uh oh!

aaradhychinche-alt commented Apr 29, 2026

Uh oh!

aaradhychinche-alt commented May 1, 2026

Uh oh!

aaradhychinche-alt commented May 4, 2026

Uh oh!

mbrandenburger commented May 5, 2026

Uh oh!

aaradhychinche-alt commented May 8, 2026

Uh oh!

aaradhychinche-alt commented May 12, 2026

Uh oh!

github-actions Bot commented May 18, 2026

Uh oh!

github-actions Bot commented May 18, 2026

PR Checks

Uh oh!

aaradhychinche-alt commented May 18, 2026

Uh oh!

mbrandenburger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aaradhychinche-alt commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aaradhychinche-alt commented Apr 25, 2026 •

edited

Loading