refactor: reorganize token_chaincode example into examples/token_chaincode directory

- Move token_chaincode.py from root to examples/token_chaincode/main.py
- Add async/await implementation with proper error handling
- Add comprehensive README with usage examples
- Add Dockerfile for CCAAS deployment
- Add metadata.json and connection.json for Fabric integration
- Follow same structure as ccaas example for consistency
- Improve logging and input validation

This change improves project organization and follows best practices
for Hyperledger Fabric chaincode examples.

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

Author: kmilodenisglez

examples/token_chaincode/Dockerfile

@@ -0,0 +1,31 @@
+# Dockerfile for Token Chaincode CCAAS
+# Build: docker build -t token-chaincode:latest .
+# Run: docker run -e CHAINCODE_ID=token_1.0:sha256:hash -e CHAINCODE_SERVER_ADDRESS=0.0.0.0:9999 -p 9999:9999 token-chaincode:latest
+
+FROM python:3.11-slim
+
+LABEL maintainer="fabric-chaincode-python contributors"
+LABEL description="Token Chaincode - Hyperledger Fabric Chaincode Service"
+
+# Set working directory
+WORKDIR /app
+
+# Copy the parent fabric-chaincode-python source
+COPY ../../pyproject.toml ./
+COPY ../../src ./src
+COPY ../../fabric_protos_python ./fabric_protos_python
+COPY ../../requirements.txt ./
+
+# Copy this example
+COPY . ./examples/token_chaincode
+
+# Install dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Set environment variables for CCAAS
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+
+# Run the chaincode server
+EXPOSE 9999
+CMD ["python", "-u", "examples/token_chaincode/main.py"]

examples/token_chaincode/README.md

@@ -0,0 +1,187 @@
+# Token Chaincode - CCAAS Example
+
+This directory contains a complete example of a Hyperledger Fabric Python chaincode for token management deployed as a Chaincode-as-a-Service (CCAAS).
+
+## Overview
+
+This example implements a simple token system where you can:
+- **reset** - Reset token balances for all accounts (equivalent to init)
+- **balance** - Query the token balance of an account
+- **transfer** - Transfer tokens from one account to another
+
+## Features
+
+- ✅ Async/await chaincode implementation
+- ✅ Error handling and validation
+- ✅ Logging for debugging
+- ✅ Input validation (amount must be numeric)
+- ✅ Balance checks before transfers
+- ✅ Account existence validation
+- ✅ CCAAS deployment ready
+- ✅ Docker support
+
+## Prerequisites
+
+- Hyperledger Fabric test network running (e.g., `test-network-nano-bash`)
+- Python 3.10+ with `venv`
+- Peer CLI (`peer`) configured and in PATH
+- The parent `fabric-chaincode-python` repository available
+- Docker (optional, for containerized deployment)
+
+## Quick Start
+
+### 1. Prepare Python Environment
+
+```bash
+cd /path/to/fabric-chaincode-python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 2. Install Example Dependencies
+
+```bash
+cd examples/token_chaincode
+pip install -r requirements.txt
+```
+
+### 3. Run the Chaincode Server
+
+```bash
+export CHAINCODE_ID=token_1.0:sha256:your_package_hash
+export CHAINCODE_SERVER_ADDRESS=127.0.0.1:9999
+
+cd examples/token_chaincode
+python main.py
+```
+
+The chaincode server will start and wait for connections from a Fabric peer.
+
+### 4. Invoke Chaincode Functions
+
+**Initialize/Reset tokens:**
+```bash
+peer chaincode invoke -C mychannel -n token_1.0 -c '{"function":"reset","Args":[]}'
+```
+
+**Query balance:**
+```bash
+peer chaincode query -C mychannel -n token_1.0 -c '{"function":"balance","Args":["tommy"]}'
+```
+
+**Transfer tokens:**
+```bash
+peer chaincode invoke -C mychannel -n token_1.0 -c '{"function":"transfer","Args":["tommy","jerry","100"]}'
+```
+
+**Check new balances:**
+```bash
+peer chaincode query -C mychannel -n token_1.0 -c '{"function":"balance","Args":["tommy"]}'
+peer chaincode query -C mychannel -n token_1.0 -c '{"function":"balance","Args":["jerry"]}'
+```
+
+## Docker Deployment
+
+### Build the Docker Image
+
+```bash
+docker build -t token-chaincode:latest .
+```
+
+### Run in Docker
+
+```bash
+docker run -d \
+  --name token-chaincode \
+  -e CHAINCODE_ID=token_1.0:sha256:your_hash \
+  -e CHAINCODE_SERVER_ADDRESS=0.0.0.0:9999 \
+  -p 9999:9999 \
+  token-chaincode:latest
+```
+
+### Use in Fabric Network
+
+Package and deploy the chaincode to your Fabric network following the [official Hyperledger Fabric documentation](https://hyperledger-fabric.readthedocs.io/en/latest/chaincode4ade.html).
+
+## Project Structure
+
+```
+token_chaincode/
+├── main.py               # Chaincode implementation
+├── requirements.txt      # Python dependencies
+├── Dockerfile           # Container image definition
+├── README.md           # This file
+└── metadata.json       # Chaincode metadata (optional)
+```
+
+## API Reference
+
+### Functions
+
+#### `reset`
+Initializes/resets token balances for test accounts.
+
+**Parameters:** None
+
+**Returns:** `success: b'init ok'` or error message
+
+#### `balance`
+Queries the token balance of an account.
+
+**Parameters:**
+- `account` (string): Account name
+
+**Returns:** `success: b'balance => <amount>'` or error message
+
+#### `transfer`
+Transfers tokens from one account to another.
+
+**Parameters:**
+- `from` (string): Source account name
+- `to` (string): Destination account name
+- `amount` (string): Amount to transfer (must be convertible to integer)
+
+**Returns:** `success: b'transfer ok'` or error message
+
+## Error Handling
+
+The chaincode includes comprehensive error handling:
+- Account not found errors
+- Insufficient balance errors
+- Invalid amount errors (non-numeric input)
+- Missing argument errors
+
+All errors are logged and returned with descriptive messages.
+
+## Testing
+
+Run the included tests:
+
+```bash
+cd /path/to/fabric-chaincode-python
+pytest tests/
+```
+
+## Logging
+
+The chaincode uses Python's standard logging module with DEBUG level logging.
+
+To adjust logging level, modify the `logging.basicConfig()` call in `main.py`:
+
+```python
+logging.basicConfig(level=logging.INFO)  # Change to INFO, WARNING, etc.
+```
+
+## Related Examples
+
+- [Asset Transfer (CCAAS)](../ccaas/) - More complex asset management example
+- [Fabric Chaincode Python Documentation](../../README.md)
+
+## License
+
+This example is licensed under the Apache-2.0 License. See [LICENSE](../../LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

examples/token_chaincode/connection.json

@@ -0,0 +1,3 @@
+{
+  "address": "token-chaincode:9999"
+}

examples/token_chaincode/main.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+# Copyright the fabric-chaincode-python contributors. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Token Chaincode Example (CCAAS)
+
+This is a simple token transfer chaincode that demonstrates:
+- Token initialization (minting)
+- Balance queries
+- Token transfers between accounts
+- State management with the Fabric ledger
+
+Deploy this as a Chaincode-as-a-Service (CCAAS) in Fabric.
+"""
+
+import sys
+import logging
+
+from src.fabric_shim.interfaces import Chaincode, ChaincodeStubInterface
+from src.fabric_shim.server import start
+from src.fabric_shim.response import ResponseCode
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.DEBUG)
+
+
+class TokenChaincode(Chaincode):
+    """Simple token management chaincode"""
+
+    async def init(self, stub: ChaincodeStubInterface):
+        """
+        Chaincode initialization - issues initial tokens to accounts
+        
+        Args:
+            stub: ChaincodeStubInterface for ledger access
+            
+        Returns:
+            Success or error response
+        """
+        logger.info("=== TokenChaincode Init ===")
+        try:
+            # Initialize token balances for test accounts
+            await stub.put_state('tommy', b'1000')  # Issue 1000 tokens to tommy
+            await stub.put_state('jerry', b'1000')  # Issue 1000 tokens to jerry
+            
+            logger.info("Token initialization successful")
+            return ResponseCode.SUCCESS, b'init ok'
+        except Exception as e:
+            logger.error(f"Error during init: {str(e)}")
+            return ResponseCode.ERROR, str(e).encode()
+
+    async def invoke(self, stub: ChaincodeStubInterface):
+        """
+        Chaincode invocation handler - routes to appropriate function
+        
+        Args:
+            stub: ChaincodeStubInterface for ledger access
+            
+        Returns:
+            Response from the invoked function
+        """
+        logger.info("=== TokenChaincode Invoke ===")
+        try:
+            fcn, args = stub.get_function_and_parameters()
+            logger.info(f"Invoking function: {fcn} with args: {args}")
+
+            if fcn == 'reset':
+                return await self.init(stub)
+            elif fcn == 'balance':
+                if len(args) < 1:
+                    return ResponseCode.ERROR, b'balance requires 1 argument: account'
+                return await self.balance(stub, args[0])
+            elif fcn == 'transfer':
+                if len(args) < 3:
+                    return ResponseCode.ERROR, b'transfer requires 3 arguments: from, to, amount'
+                return await self.transfer(stub, args[0], args[1], args[2])
+            else:
+                return ResponseCode.ERROR, f'method {fcn} not supported'.encode()
+
+        except Exception as e:
+            logger.error(f"Error during invoke: {str(e)}")
+            return ResponseCode.ERROR, str(e).encode()
+
+    async def balance(self, stub: ChaincodeStubInterface, account: str):
+        """
+        Query the balance of an account
+        
+        Args:
+            stub: ChaincodeStubInterface for ledger access
+            account: Account name to query
+            
+        Returns:
+            Balance information
+        """
+        logger.info(f"Querying balance for account: {account}")
+        try:
+            value = await stub.get_state(account)
+            if not value:
+                return ResponseCode.ERROR, f'account {account} not found'.encode()
+            
+            logger.info(f"Balance for {account}: {value.decode()}")
+            return ResponseCode.SUCCESS, b'balance => ' + value
+        except Exception as e:
+            logger.error(f"Error querying balance: {str(e)}")
+            return ResponseCode.ERROR, str(e).encode()
+
+    async def transfer(self, stub: ChaincodeStubInterface, owner: str, to: str, value: str):
+        """
+        Transfer tokens from one account to another
+        
+        Args:
+            stub: ChaincodeStubInterface for ledger access
+            owner: Source account
+            to: Destination account
+            value: Amount to transfer
+            
+        Returns:
+            Success or error response
+        """
+        logger.info(f"Transferring {value} tokens from {owner} to {to}")
+        try:
+            value = int(value)
+            
+            # Get owner balance
+            owner_balance_bytes = await stub.get_state(owner)
+            if not owner_balance_bytes:
+                return ResponseCode.ERROR, f'account {owner} not found'.encode()
+            
+            owner_balance = int(owner_balance_bytes.decode())
+            
+            # Check sufficient balance
+            if owner_balance < value:
+                return ResponseCode.ERROR, f'insufficient balance: {owner_balance} < {value}'.encode()
+            
+            # Get recipient balance
+            to_balance_bytes = await stub.get_state(to)
+            if not to_balance_bytes:
+                return ResponseCode.ERROR, f'account {to} not found'.encode()
+            
+            to_balance = int(to_balance_bytes.decode())
+            
+            # Update balances
+            owner_balance -= value
+            to_balance += value
+            
+            # Write updated balances to ledger
+            await stub.put_state(owner, str(owner_balance).encode())
+            await stub.put_state(to, str(to_balance).encode())
+            
+            logger.info(f"Transfer successful: {owner} ({owner_balance}), {to} ({to_balance})")
+            return ResponseCode.SUCCESS, b'transfer ok'
+        except ValueError:
+            return ResponseCode.ERROR, f'invalid amount: {value}'.encode()
+        except Exception as e:
+            logger.error(f"Error during transfer: {str(e)}")
+            return ResponseCode.ERROR, str(e).encode()
+
+
+if __name__ == '__main__':
+    # Start the chaincode server
+    logger.info("Starting TokenChaincode server...")
+    start(TokenChaincode())

examples/token_chaincode/metadata.json

@@ -0,0 +1,4 @@
+{
+  "type": "ccaas",
+  "label": "token-chaincode"
+}