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

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

Author: aaradhychinche-alt

examples/chaincode-to-fsc/README.md

@@ -0,0 +1,80 @@
+# Chaincode -> FSC Example (Asset Transfer)
+
+## Topology
+
+This example uses a single process to simulate the tutorial roles below:
+
+* Client (CLI)
+* FSC Node (initiator flow)
+* Endorser (responder flow)
+* Fabric-X (ordering + finality)
+
+### Flow diagram
+
+```text
+Client (CLI)
+  |
+  v
+FSC Node (initiator flow)
+  |-- ReadAsset(id)
+  |-- validate transfer
+  |-- prepare transaction
+  |-- collect endorsement
+  |-- submit transaction
+  |-- verify state
+  v
+Endorser (responder flow)
+  |
+  v
+Fabric-X (ordering + finality)
+```
+
+## API
+
+The example follows the same asset-transfer shape as Fabric chaincode:
+
+* `ReadAsset(id string)`
+* `TransferAsset(id, newOwner string)`
+
+`ReadAsset` reads the current asset state. `TransferAsset` drives the FSC flow, submits the transaction, and verifies the updated state after finality.
+
+These functions mirror the Fabric asset-transfer chaincode, but are implemented using FSC views instead of on-ledger chaincode execution.
+
+## Execution
+
+Run the example with:
+
+```bash
+go run ./cmd/token-transfer --asset-id a1 --new-owner bob
+```
+
+## Example output
+
+```text
+reading asset
+validating transfer
+preparing transaction (phase: pre-submission)
+endorsing transaction
+submitting transaction (phase: post-submission)
+verifying state
+success: asset a1 now owned by bob
+```
+
+Each line corresponds to a stage in the FSC transaction lifecycle.
+
+## Notes
+
+* The roles are simulated in a single process.
+* In this example, client and endorser roles are simulated within a single process for simplicity, but the flow structure matches how FSC nodes would interact in a real network.
+* The example stays tutorial-style and intentionally small.
+* The code mirrors the chaincode asset-transfer API without extra abstractions.
+
+## Future Work
+
+This example currently simulates all roles in a single process for simplicity.
+
+The next step is to extend this into a real multi-node FSC + Fabric-X setup where:
+
+* separate FSC nodes act as clients and endorsers
+* communication happens over networked views
+* ordering and finality are handled by a real Fabric-X deployment

examples/chaincode-to-fsc/cmd/token-transfer/main.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/hyperledger-labs/fabric-smart-client/examples/chaincode-to-fsc/internal/flow"
+)
+
+func main() {
+	assetID := flag.String("asset-id", "", "asset identifier")
+	newOwner := flag.String("new-owner", "", "new owner")
+	flag.Parse()
+
+	if *assetID == "" || *newOwner == "" {
+		fmt.Fprintln(os.Stderr, "usage: go run ./cmd/token-transfer --asset-id <id> --new-owner <owner>")
+		os.Exit(2)
+	}
+
+	result, err := flow.TransferAsset(*assetID, *newOwner)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println(result)
+}

examples/chaincode-to-fsc/go.mod

@@ -0,0 +1,3 @@
+module github.com/hyperledger-labs/fabric-smart-client/examples/chaincode-to-fsc
+
+go 1.25.7

examples/chaincode-to-fsc/internal/flow/transfer_asset.go

@@ -0,0 +1,58 @@
+package flow
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/hyperledger-labs/fabric-smart-client/examples/chaincode-to-fsc/internal/model"
+	"github.com/hyperledger-labs/fabric-smart-client/examples/chaincode-to-fsc/internal/protocol"
+)
+
+func ReadAsset(assetID string) (model.Asset, error) {
+	if strings.TrimSpace(assetID) == "" {
+		return model.Asset{}, fmt.Errorf("asset id cannot be empty")
+	}
+
+	asset, err := protocol.GetAsset(assetID)
+	if err != nil {
+		return model.Asset{}, fmt.Errorf("read asset %s: %w", assetID, err)
+	}
+
+	return asset, nil
+}
+
+func TransferAsset(assetID, newOwner string) (string, error) {
+	if strings.TrimSpace(newOwner) == "" {
+		return "", fmt.Errorf("new owner cannot be empty")
+	}
+
+	fmt.Println("reading asset")
+	asset, err := ReadAsset(assetID)
+	if err != nil {
+		return "", fmt.Errorf("read asset failed: %w", err)
+	}
+
+	fmt.Println("validating transfer")
+	if asset.Owner == newOwner {
+		return "", fmt.Errorf("asset %s is already owned by %s", assetID, newOwner)
+	}
+
+	fmt.Println("preparing transaction (phase: pre-submission)")
+	fmt.Println("endorsing transaction")
+	if err := protocol.SubmitTransfer(assetID, newOwner); err != nil {
+		return "", fmt.Errorf("submit transfer failed: %w", err)
+	}
+
+	fmt.Println("submitting transaction (phase: post-submission)")
+	fmt.Println("verifying state")
+	updated, err := ReadAsset(assetID)
+	if err != nil {
+		return "", fmt.Errorf("verify asset failed: %w", err)
+	}
+	if updated.Owner != newOwner {
+		return "", fmt.Errorf("transfer verification failed: expected owner %s, got %s", newOwner, updated.Owner)
+	}
+
+	result := fmt.Sprintf("success: asset %s now owned by %s", updated.ID, updated.Owner)
+	return result, nil
+}

examples/chaincode-to-fsc/internal/model/asset.go

@@ -0,0 +1,6 @@
+package model
+
+type Asset struct {
+	ID    string
+	Owner string
+}

examples/chaincode-to-fsc/internal/protocol/fabricx.go

@@ -0,0 +1,32 @@
+package protocol
+
+import (
+	"fmt"
+
+	"github.com/hyperledger-labs/fabric-smart-client/examples/chaincode-to-fsc/internal/model"
+)
+
+var assets = map[string]model.Asset{
+	"a1": {
+		ID:    "a1",
+		Owner: "alice",
+	},
+}
+
+func GetAsset(id string) (model.Asset, error) {
+	asset, ok := assets[id]
+	if !ok {
+		return model.Asset{}, fmt.Errorf("asset %s not found", id)
+	}
+	return asset, nil
+}
+
+func SubmitTransfer(id, newOwner string) error {
+	asset, ok := assets[id]
+	if !ok {
+		return fmt.Errorf("asset %s not found", id)
+	}
+	asset.Owner = newOwner
+	assets[id] = asset
+	return nil
+}