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,141 @@
+# 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 3rd 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 Bob using Option 5.
+```
+
+#### 5. Run Tests
+
+```bash
+# Run all basic tests
+./multi_user_dashboard.sh
+
+# Chosing Option 7.
+```
+
+## 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,
+		},
+	},
+}

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

@@ -0,0 +1,102 @@
+package assets
+
+import (
+	"github.com/hyperledger-labs/cc-tools/assets"
+)
+
+// Escrow defines the asset type for programmable conditional payment contracts.
+// This enables secure, trustless transactions where funds are held in escrow until
+// predefined conditions are met. The escrow uses cryptographic hash verification
+// to ensure condition fulfillment.
+//
+// Lifecycle States:
+//   - Active: Funds locked, awaiting condition verification
+//   - ReadyForRelease: Condition verified, awaiting release
+//   - Released: Funds transferred to seller
+//   - Refunded: Funds returned to buyer
+//
+// Security Model:
+//   - conditionValue: SHA-256 hash of (secret + parcelId) for atomic condition verification
+//   - buyerCertHash: Ensures only the buyer can initiate refunds
+//   - Seller must provide correct secret and parcelId to release funds
+var Escrow = assets.AssetType{
+	Tag:         "escrow",
+	Label:       "Programmable Escrow",
+	Description: "Confidential escrow contract with programmable conditions",
+
+	Props: []assets.AssetProp{
+		{
+			Tag:      "escrowId",
+			Label:    "Escrow ID",
+			DataType: "string",
+			Required: true,
+			IsKey:    true,
+		},
+		{
+			Tag:      "buyerPubKey",
+			Label:    "Buyer Public Key",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "sellerPubKey",
+			Label:    "Seller Public Key",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "buyerWalletUUID",
+			Label:    "Buyer Wallet UUID",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "sellerWalletUUID",
+			Label:    "Seller Wallet UUID",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "amount",
+			Label:    "Escrowed Amount",
+			DataType: "number",
+			Required: true,
+		},
+		{
+			Tag:      "assetType",
+			Label:    "Asset Type Reference",
+			DataType: "->digitalAsset", // References digitalAsset symbol
+			Required: true,
+		},
+		{
+			Tag:      "parcelId",
+			Label:    "Parcel ID",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "conditionValue",
+			Label:    "Condition Value",
+			DataType: "string",
+			Required: true,
+		},
+		{
+			Tag:      "status",
+			Label:    "Escrow Status",
+			DataType: "string", // "Active", "Released", "Refunded"
+			Required: true,
+		},
+		{
+			Tag:      "createdAt",
+			Label:    "Creation Timestamp",
+			DataType: "datetime",
+			Required: false,
+		},
+		{
+			Tag:      "buyerCertHash",
+			Label:    "Buyer Certificate Hash",
+			DataType: "string",
+			Required: true,
+		},
+	},
+}