merge: sync release-2.5 protobuf migration into main

Signed-off-by: kmilo <kmilo.denis.glez@yandex.com>

Author: kmilodenisglez

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 25
     # Run steps at the repository root (no custom working-directory)
     steps:
       - uses: actions/checkout@v4
@@ -58,6 +58,11 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -r requirements.txt pytest pytest-asyncio
 
+      - name: Install official Fabric protobuf bindings
+        run: |
+          chmod +x scripts/install_fabric_protos.sh
+          PYTHON_BIN=python ./scripts/install_fabric_protos.sh
+
       - name: Run tests
         run: |
           python -m pytest -q

.gitignore

@@ -149,8 +149,8 @@ dmypy.json
 *.sh text eol=lf
 
 # Generated protobuf/python bindings (src/protos is still ignored)
-# If you want to commit generated bindings at top-level, do not ignore `fabric_protos_python/` or `protos/`.
-# (We will generate into `fabric_protos_python/` and track it in git.)
+# Optional local generation can target `fabric_protos/` for debugging,
+# but runtime dependencies should come from official `hyperledger/fabric-protos` bindings.
 
 # Secrets and certificates
 *.pem

PROTOS.md

@@ -1,65 +1,57 @@
-Protobufs / How to handle `fabric-protos`
-=========================================
+Protobufs / How this project uses `fabric-protos`
+===============================================
 
-Summary
--------
-
-Hyperledger Fabric defines its gRPC interfaces in the `fabric-protos` repository
-(Apache-2.0). When implementing a Python shim you generally have two practical
-options:
-
-1. "Submodule and generate": Add `fabric-protos` as a submodule (or reference a
-	 fixed tag) and generate Python bindings (`*_pb2.py`, `*_pb2_grpc.py`) using
-	 `grpc_tools.protoc` or `protoc` with a Python plugin. The provided
-	 `scripts/gen_protos.sh` can be used for this. Optionally include the
-	 generated files in the package for releases to simplify consumers' setup.
-
-2. "Package pre-generated protos": Commit the generated Python bindings into
-	 the repository/package and document the exact `fabric-protos` version used to
-	 generate them. This avoids requiring consumers to generate bindings locally.
-
-Recommendation (practical balance)
-----------------------------------
-
-- Use `fabric-protos` as a submodule pinned to the exact tag you support. This
-	preserves provenance and makes regenerating bindings reproducible.
-- Keep `scripts/gen_protos.sh` in the repo as a canonical way to regenerate
-	bindings. Commit generated bindings for release artifacts (or for ease of
-	testing), but avoid mixing `.proto` sources into the runtime package unless
-	required.
-- In CI, either regenerate the bindings and compare them with the committed
-	files, or regenerate them as part of the release build to ensure consistency.
-- Avoid publishing a PyPI package name that could be confused with an official
-	upstream package (e.g. `fabric-protos-python`). If publishing generated
-	bindings, choose a clear, distinct package name and document compatibility.
-
-Practical steps (example)
+Current integration model
 -------------------------
 
-1. Add `fabric-protos` as a submodule and pin to a tag:
+This project now consumes official Python protobuf bindings from
+`hyperledger/fabric-protos`.
+
+- Package name: `hyperledger-fabric-protos`
+- Import namespace used by this repository: `fabric_protos`
+
+Install with:
 
 ```bash
-git submodule add --depth 1 -b v2.5.0 https://github.com/hyperledger/fabric-protos.git protos/fabric-protos
-git submodule update --init --recursive
+PYTHON_BIN=python ./scripts/install_fabric_protos.sh
 ```
 
-2. Generate Python bindings (run from the repository root):
+Why this model
+--------------
+
+- Avoids vendored generated protobuf drift inside this repository.
+- Keeps protocol bindings aligned with the upstream Fabric protobuf source.
+- Simplifies release and maintenance for `fabric-chaincode-python`.
+
+Version compatibility
+---------------------
+
+Use dependency ranges compatible with upstream Python bindings:
+
+- `protobuf>=5.27.0,<6.0.0`
+- `grpcio>=1.83.1,<2.0.0`
+
+The installer script uses the following order:
+
+1. Local `../fabric-protos` checkout (runs `make pythonbindings`)
+2. PyPI `hyperledger-fabric-protos` package (if complete)
+3. Official `hyperledger/fabric-protos` git checkout at pinned commit,
+   then local build/install of `bindings/python`
+
+Local regeneration (optional)
+-----------------------------
+
+For debugging or contributor workflows, bindings can still be generated from
+a local `fabric-protos` checkout:
 
 ```bash
-cd ./fabric-chaincode-python
-PROTO_SRC=protos/fabric-protos bash scripts/gen_protos.sh
-# generated files will be placed where the script is configured (e.g. fabric_protos_python/)
+PROTO_SRC=/path/to/fabric-protos OUT_DIR=$PWD/fabric_protos bash scripts/gen_protos.sh
 ```
 
-3. In CI: either regenerate and `git diff` against committed bindings to detect
-	 drift, or regenerate in the build environment so wheel artifacts include the
-	 bindings.
+This is optional and should not be required for normal runtime use.
 
 License
 -------
 
-`fabric-protos` is licensed under Apache-2.0. If you include `.proto` files or
-generated bindings from that repository in your project, retain the original
-license notice (do not remove the `LICENSE` files from the `fabric-protos`
-source when copying). This is important if you plan to contribute or migrate the
-project to Hyperledger Labs.
+`fabric-protos` is Apache-2.0. If distributing generated bindings yourself,
+keep original licensing notices intact.

README.md

@@ -12,8 +12,9 @@ Requirements
 - Python 3.10+ (3.11 recommended)
 - See `requirements.txt` for runtime dependencies. Key packages:
 	- `grpcio==1.83.1`
-	- `protobuf>=7.35.1`
+	- `protobuf>=5.27.0,<6.0.0`
 	- `grpclib==0.4.3`
+	- `hyperledger-fabric-protos` (installed via `scripts/install_fabric_protos.sh`)
 
 Quick start (development)
 -------------------------
@@ -26,6 +27,7 @@ python3 -m venv .venv
 source .venv/bin/activate
 python -m pip install --upgrade pip
 pip install -r requirements.txt
+PYTHON_BIN=python ./scripts/install_fabric_protos.sh
 ```
 
 Run tests:
@@ -46,14 +48,25 @@ python -m build --wheel --no-isolation
 
 Protobuf bindings
 -----------------
-This repository contains generated Python protobuf bindings for Hyperledger
-Fabric under the `fabric_protos_python/` package. The project also includes a
-`scripts/gen_protos.sh` helper to regenerate bindings from the `fabric-protos`
-source (recommended to use a pinned tag/submodule for reproducible results).
+This repository consumes the official Python bindings published from
+`hyperledger/fabric-protos`:
 
-If you regenerate protos in CI or locally, ensure the `protobuf` runtime used
-to generate the files is compatible with the installed `protobuf` package
-(see `requirements.txt`).
+- Package name: `hyperledger-fabric-protos`
+- Import namespace: `fabric_protos`
+
+Bindings are installed from official `hyperledger/fabric-protos` sources by
+`scripts/install_fabric_protos.sh`, with validation that required generated
+modules are present.
+
+Install or refresh official bindings with:
+
+```bash
+PYTHON_BIN=python ./scripts/install_fabric_protos.sh
+```
+
+No vendored protobuf runtime package is required in this repository.
+If you need to regenerate bindings locally for debugging, use
+`scripts/gen_protos.sh` and keep generated/runtime versions compatible.
 
 Running a chaincode service (example)
 ------------------------------------
@@ -67,7 +80,7 @@ export CHAINCODE_SERVER_ADDRESS=127.0.0.1:9999
 Then start the example service (if `main.py` or an example is present):
 
 ```bash
-python main.py
+./.venv/bin/python examples/ccaas/asset-transfer-basic/main.py
 ```
 
 Contributing

examples/ccaas/asset-transfer-basic/README.md

@@ -28,6 +28,7 @@ cd /path/to/fabric-chaincode-python
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
+PYTHON_BIN=python ./scripts/install_fabric_protos.sh
 ```
 
 ### 2. Package the Chaincode
@@ -186,8 +187,9 @@ Tells Fabric that this is a CCAAS package:
 ### Server won't start
 - Ensure `CHAINCODE_ID` matches the package-id from `peer lifecycle chaincode install`
 - Check that `connection.json` address is accessible from the peer
-- Verify dependencies are installed: `pip install -r requirements.txt`
+- Verify dependencies are installed: `pip install -r requirements.txt && PYTHON_BIN=python ./scripts/install_fabric_protos.sh`
 - Verify you're using the project venv: `./.venv/bin/python -c "import grpc; print(grpc.__version__)"`
+- Verify Fabric protobuf bindings are importable: `./.venv/bin/python -c "from fabric_protos.peer import chaincode_shim_pb2"`
 
 ### Peer can't reach chaincode
 - Check firewall rules allowing port 9999

examples/ccaas/asset-transfer-basic/main.py

@@ -27,7 +27,7 @@
 from src.fabric_shim.interfaces import Chaincode, ChaincodeStubInterface
 from src.fabric_shim.server import start
 from src.fabric_shim.response import ResponseCode
-from fabric_protos_python.peer import proposal_response_pb2 as pb
+from fabric_protos.peer import proposal_response_pb2 as pb
 
 
 class Asset:

examples/ccaas/asset-transfer-sbe/README.md

@@ -40,27 +40,22 @@ cd /path/to/fabric-chaincode-python
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
+PYTHON_BIN=python ./scripts/install_fabric_protos.sh
 ```
 
-### 2. Install Example Dependencies
-
-```bash
-cd examples/ccaas/asset-transfer-sbe
-pip install -r requirements.txt
-```
-
-### 3. Run the Chaincode Server
+### 2. Run the Chaincode Server
 
 ```bash
+cd /path/to/fabric-chaincode-python/examples/ccaas/asset-transfer-sbe
 export CHAINCODE_ID=asset_transfer_sbe_1:<package_hash>
 export CHAINCODE_SERVER_ADDRESS=127.0.0.1:9999
 
-python main.py
+../../../.venv/bin/python main.py
 ```
 
 The chaincode server will start and wait for connections from a Fabric peer.
 
-### 4. Invoke Chaincode Functions
+### 3. Invoke Chaincode Functions
 
 **Create asset:**
 ```bash

examples/ccaas/asset-transfer-sbe/main.py

@@ -16,7 +16,7 @@
 if str(REPO_ROOT) not in sys.path:
     sys.path.insert(0, str(REPO_ROOT))
 
-from fabric_protos_python.peer import proposal_response_pb2 as pb
+from fabric_protos.peer import proposal_response_pb2 as pb
 from src.fabric_shim.interfaces import Chaincode, ChaincodeStubInterface
 from src.fabric_shim.response import ResponseCode
 from src.fabric_shim.server import start