feature(samples): confidential escrow example - LFX25

samples/chaincode/Makefile

@@ -6,7 +6,7 @@
 TOP = ../..
 include $(TOP)/build.mk
 
-SUB_DIRS = auction auction-go echo echo-go kv-test kv-test-go
+SUB_DIRS = auction auction-go echo echo-go kv-test kv-test-go confidential-escrow
 
 build test clean clobber:
 	$(foreach DIR, $(SUB_DIRS), $(MAKE) -C $(DIR) $@ || exit ;)

samples/chaincode/confidential-escrow/.env.alice

@@ -0,0 +1,15 @@
+export CC_ID=confidential-escrow
+export CHANNEL_NAME=mychannel
+export CORE_PEER_ADDRESS=localhost:7051
+export CORE_PEER_ID=peer0.org1.example.com
+export CORE_PEER_ORG_NAME=org1
+export CORE_PEER_LOCALMSPID=Org1MSP
+export CORE_PEER_MSPCONFIGPATH=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp
+export CORE_PEER_TLS_CERT_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.crt
+export CORE_PEER_TLS_ENABLED="true"
+export CORE_PEER_TLS_KEY_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.key
+export CORE_PEER_TLS_ROOTCERT_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
+export ORDERER_CA=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem
+export GATEWAY_CONFIG=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/connection-org1.yaml
+export FPC_ENABLED=true
+export RUN_CCAAS=true

samples/chaincode/confidential-escrow/.env.bob

@@ -0,0 +1,16 @@
+export CC_ID=confidential-escrow
+export CHANNEL_NAME=mychannel
+export CORE_PEER_ADDRESS=localhost:9051
+export CORE_PEER_ID=peer0.org2.example.com
+export CORE_PEER_ORG_NAME=org2
+export CORE_PEER_LOCALMSPID=Org2MSP
+export CORE_PEER_MSPCONFIGPATH=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp
+export CORE_PEER_TLS_CERT_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/server.crt
+export CORE_PEER_TLS_ENABLED="true"
+export CORE_PEER_TLS_KEY_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/server.key
+export CORE_PEER_TLS_ROOTCERT_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt
+export ORDERER_CA=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem
+export GATEWAY_CONFIG=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/connection-org2.yaml
+export FPC_ENABLED=true
+export RUN_CCAAS=true
+

samples/chaincode/confidential-escrow/.env.example

@@ -0,0 +1,15 @@
+export CC_ID=confidential-escrow
+export CHANNEL_NAME=mychannel
+export CORE_PEER_ADDRESS=localhost:7051
+export CORE_PEER_ID=peer0.org1.example.com
+export CORE_PEER_ORG_NAME=org1
+export CORE_PEER_LOCALMSPID=Org1MSP
+export CORE_PEER_MSPCONFIGPATH=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp
+export CORE_PEER_TLS_CERT_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.crt
+export CORE_PEER_TLS_ENABLED="true"
+export CORE_PEER_TLS_KEY_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.key
+export CORE_PEER_TLS_ROOTCERT_FILE=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
+export ORDERER_CA=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem
+export GATEWAY_CONFIG=$FPC_PATH/samples/deployment/test-network/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/connection-org1.yaml
+export FPC_ENABLED=true
+export RUN_CCAAS=true

samples/chaincode/confidential-escrow/.gitignore

@@ -0,0 +1,10 @@
+ecc
+ecc-bundle
+enclave.json
+private.pem
+public.pem
+mrenclave
+details.env
+
+.env
+*.bak

samples/chaincode/confidential-escrow/Makefile

@@ -0,0 +1,7 @@
+TOP = ../../..
+include $(TOP)/ecc_go/build.mk
+
+CC_NAME ?= confidential-escrow
+
+EGO_CONFIG_FILE = $(FPC_PATH)/samples/chaincode/confidential-escrow/confidentialEscrowEnclave.json
+ECC_MAIN_FILES=$(FPC_PATH)/samples/chaincode/confidential-escrow

samples/chaincode/confidential-escrow/README.md

@@ -0,0 +1,187 @@
+# Confidential Escrow Chaincode
+
+A privacy-preserving escrow system built on Hyperledger Fabric Private Chaincode (FPC) that enables secure digital asset management with programmable conditional payments.
+
+## Overview
+
+This chaincode implements a confidential escrow mechanism for digital assets, combining:
+
+- **Privacy-Preserving Transactions**: All transaction data is encrypted within Intel SGX enclaves
+- **Programmable Escrow Contracts**: Automated conditional fund releases based on cryptographic verification
+- **Multi-Asset Support**: Manage multiple token types within individual wallets
+- **Certificate-Based Authorization**: Fine-grained access control using X.509 certificate hashes
+
+## Architecture
+
+### Core Components
+
+**Assets**
+
+- `DigitalAsset`: Fungible tokens with controlled supply (CBDC, stablecoins, etc.)
+- `Wallet`: User accounts supporting multiple asset types with separate available and escrowed balances
+- `Escrow`: Smart contracts holding funds pending condition fulfillment
+- `UserDirectory`: Privacy-preserving public key to wallet UUID mapping
+
+**Transaction Operations**
+
+- Asset lifecycle: Create, mint, transfer, burn
+- Wallet management: Create wallets, query balances
+- Escrow workflow: Lock funds, verify conditions, release or refund
+
+## Project Structure
+
+```
+confidential-escrow/
+├── chaincode/
+│   ├── assets/           # Asset type definitions
+│   ├── transactions/     # Transaction handlers
+│   ├── header/           # Chaincode metadata
+│   ├── escrow.go         # Main chaincode implementation
+│   ├── server.go         # CCaaS server setup
+│   └── setup.go          # Component registration
+├── main.go               # Entry point
+├── main.sh               # Deployment and test automation
+└── README.md             # This file
+```
+
+### Security Model
+
+1. **Access Control**: All operations require valid certificate hash verification
+2. **Atomic Escrow**: Funds move from available to escrowed balance during lock, preventing double-spending
+3. **Condition Verification**: SHA-256 hash of `(secret + parcelId)` ensures only authorized parties can release funds
+4. **Confidential Execution**: FPC ensures transaction details remain private within SGX enclaves
+
+## Running Procedure
+
+### Prerequisites
+
+- FPC is properly set up and built
+- `multi_user_dashboard.sh ` script is placed in the chaincode directory
+- `.env.alice` and `.env.bob` file is present
+
+### Setup Files
+
+**1. Set FPC_PATH:**
+
+```bash
+export FPC_PATH=/project/src/github.com/hyperledger/fabric-private-chaincode
+```
+
+### Running Procedure
+
+#### 1. In 1st terminal window - Setup and Deploy
+
+```bash
+# Get inside dev env
+make -C $FPC_PATH/utils/docker run-dev
+cd samples/chaincode/confidential-escrow
+
+# Interactive menu
+./multi_user_dashboard.sh
+
+# Choose Option 1. or 2. as per your setup condn
+```
+
+#### 2. In 2nd terminal window - Docker Environment (`Alice`)
+
+```bash
+# Enter docker container
+docker exec -it fpc-development-main /bin/bash
+cd samples/chaincode/confidential-escrow
+
+# Interactive menu
+./multi_user_dashboard.sh
+
+# Setup Alice using Option 3.
+```
+
+#### 3. In 3rd terminal window - Docker Environment (`Bob`)
+
+```bash
+# Enter docker container
+docker exec -it fpc-development-main /bin/bash
+cd samples/chaincode/confidential-escrow
+
+# Interactive menu
+./multi_user_dashboard.sh
+
+# Setup Bob using Option 4.
+```
+
+#### 4. In 4th terminal window - Docker Environment (`Monitor`)
+
+```bash
+# Enter docker container
+docker exec -it fpc-development-main /bin/bash
+cd samples/chaincode/confidential-escrow
+
+# Interactive menu
+./multi_user_dashboard.sh
+
+# Setup Monitor using Option 5.
+```
+
+#### 5. Run Tests
+
+```bash
+# Run all basic tests
+./multi_user_dashboard.sh
+
+# Chosing Option 7. (One can run it from any terminal)
+```
+
+## Escrow Workflow
+
+### Step 1: Create Wallets
+
+Before any escrow operations, both parties must have wallets:
+
+1. **Alice** creates her wallet via Terminal 2 (Option 3 - currently created automatically)
+2. **Bob** creates his wallet via Terminal 3 (Option 4 - currently created automatically)
+3. **Monitor** (Terminal 4, Option 5) can observe all wallet creations and transactions in real-time
+
+### Step 2: Create Escrow
+
+Once both wallets exist, either party can create an escrow using `createAndLockEscrow`. The buyer locks funds by specifying:
+
+- Buyer/seller public keys
+- Amount and asset type
+- `parcelId` and `secret` (used for condition verification)
+
+### Step 3: Complete Escrow
+
+Two possible outcomes:
+
+| Operation   | Who Calls | When                                        | Result                   |
+| ----------- | --------- | ------------------------------------------- | ------------------------ |
+| **Release** | Seller    | Condition fulfilled (e.g., goods delivered) | Funds transfer to seller |
+| **Refund**  | Buyer     | Condition not met or cancelled              | Funds return to buyer    |
+
+### Release vs Refund
+
+- **Release** (`releaseEscrow`): Seller provides correct `secret + parcelId` to prove fulfillment. Funds move from buyer's escrow balance to seller's available balance. Status → `Released`.
+
+- **Refund** (`refundEscrow`): Buyer cancels an active escrow. No secret needed. Funds return to buyer's available balance. Status → `Refunded`.
+
+Both operations only work on `Active` escrows.
+
+## Troubleshooting
+
+**Network already running?**
+If your Fabric test-network is already up, comment out the `network.sh down` and `network.sh up` lines in `test.sh` to avoid restarting it:
+
+```bash
+# In test.sh, comment these lines:
+# run_cmd "./network.sh down" "Bringing down network"
+# run_cmd "./network.sh up createChannel -ca" "Starting network"
+```
+
+## Contributing
+
+When adding new features:
+
+1. Define asset types in `chaincode/assets/`
+2. Implement transaction logic in `chaincode/transactions/`
+3. Register new components in `chaincode/setup.go`
+4. Add test cases to `main.sh`
+5. Update this README with usage examples

samples/chaincode/confidential-escrow/chaincode/assets/digital_asset.go

@@ -0,0 +1,62 @@
+package assets
+
+import (
+	"github.com/hyperledger-labs/cc-tools/assets"
+)
+
+// DigitalAssetToken defines the asset type for fungible digital tokens.
+// This represents confidential digital currencies such as Central Bank Digital Currencies (CBDC)
+// or tokenized assets. Each token type has a fixed supply controlled by the issuer.
+//
+// Security: The issuerHash ensures only authorized entities can mint/burn tokens.
+var DigitalAssetToken = assets.AssetType{
+	Tag:         "digitalAsset",
+	Label:       "Digital Asset Token",
+	Description: "Confidential digital currency token (e.g., CBDC)",
+
+	Props: []assets.AssetProp{
+		{
+			Tag:      "name",
+			Label:    "Token Name",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "symbol",
+			Label:    "Token Symbol",
+			DataType: "string",
+			Required: true,
+			IsKey:    true,
+		},
+		{
+			Tag:      "decimals",
+			Label:    "Decimal Places",
+			DataType: "number",
+			Required: true,
+		},
+		{
+			Tag:      "totalSupply",
+			Label:    "Total Supply",
+			DataType: "number",
+			Required: true,
+		},
+		{
+			Tag:      "issuerHash",
+			Label:    "Issuer Certificate Hash",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "owner",
+			Label:    "Owner Identity",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "issuedAt",
+			Label:    "Issued At",
+			DataType: "datetime",
+			Required: false,
+		},
+	},
+}