|
| 1 | +# Confidential Escrow Chaincode |
| 2 | + |
| 3 | +A privacy-preserving escrow system built on Hyperledger Fabric Private Chaincode (FPC) that enables secure digital asset management with programmable conditional payments. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This chaincode implements a confidential escrow mechanism for digital assets, combining: |
| 8 | + |
| 9 | +- **Privacy-Preserving Transactions**: All transaction data is encrypted within Intel SGX enclaves |
| 10 | +- **Programmable Escrow Contracts**: Automated conditional fund releases based on cryptographic verification |
| 11 | +- **Multi-Asset Support**: Manage multiple token types within individual wallets |
| 12 | +- **Certificate-Based Authorization**: Fine-grained access control using X.509 certificate hashes |
| 13 | + |
| 14 | +## Architecture |
| 15 | + |
| 16 | +### Core Components |
| 17 | + |
| 18 | +**Assets** |
| 19 | + |
| 20 | +- `DigitalAsset`: Fungible tokens with controlled supply (CBDC, stablecoins, etc.) |
| 21 | +- `Wallet`: User accounts supporting multiple asset types with separate available and escrowed balances |
| 22 | +- `Escrow`: Smart contracts holding funds pending condition fulfillment |
| 23 | +- `UserDirectory`: Privacy-preserving public key to wallet UUID mapping |
| 24 | + |
| 25 | +**Transaction Operations** |
| 26 | + |
| 27 | +- Asset lifecycle: Create, mint, transfer, burn |
| 28 | +- Wallet management: Create wallets, query balances |
| 29 | +- Escrow workflow: Lock funds, verify conditions, release or refund |
| 30 | + |
| 31 | +## Project Structure |
| 32 | + |
| 33 | +``` |
| 34 | +confidential-escrow/ |
| 35 | +├── chaincode/ |
| 36 | +│ ├── assets/ # Asset type definitions |
| 37 | +│ ├── transactions/ # Transaction handlers |
| 38 | +│ ├── header/ # Chaincode metadata |
| 39 | +│ ├── escrow.go # Main chaincode implementation |
| 40 | +│ ├── server.go # CCaaS server setup |
| 41 | +│ └── setup.go # Component registration |
| 42 | +├── main.go # Entry point |
| 43 | +├── main.sh # Deployment and test automation |
| 44 | +└── README.md # This file |
| 45 | +``` |
| 46 | + |
| 47 | +### Security Model |
| 48 | + |
| 49 | +1. **Access Control**: All operations require valid certificate hash verification |
| 50 | +2. **Atomic Escrow**: Funds move from available to escrowed balance during lock, preventing double-spending |
| 51 | +3. **Condition Verification**: SHA-256 hash of `(secret + parcelId)` ensures only authorized parties can release funds |
| 52 | +4. **Confidential Execution**: FPC ensures transaction details remain private within SGX enclaves |
| 53 | + |
| 54 | +## Running Procedure |
| 55 | + |
| 56 | +### Prerequisites |
| 57 | + |
| 58 | +- FPC is properly set up and built |
| 59 | +- `multi_user_dashboard.sh ` script is placed in the chaincode directory |
| 60 | +- `.env.alice` and `.env.bob` file is present |
| 61 | + |
| 62 | +### Setup Files |
| 63 | + |
| 64 | +**1. Set FPC_PATH:** |
| 65 | + |
| 66 | +```bash |
| 67 | +export FPC_PATH=/project/src/github.com/hyperledger/fabric-private-chaincode |
| 68 | +``` |
| 69 | + |
| 70 | +### Running Procedure |
| 71 | + |
| 72 | +#### 1. In 1st terminal window - Setup and Deploy |
| 73 | + |
| 74 | +```bash |
| 75 | +# Get inside dev env |
| 76 | +make -C $FPC_PATH/utils/docker run-dev |
| 77 | +cd samples/chaincode/confidential-escrow |
| 78 | + |
| 79 | +# Interactive menu |
| 80 | +./multi_user_dashboard.sh |
| 81 | + |
| 82 | +# Choose Option 1. or 2. as per your setup condn |
| 83 | +``` |
| 84 | + |
| 85 | +#### 2. In 2nd terminal window - Docker Environment (`Alice`) |
| 86 | + |
| 87 | +```bash |
| 88 | +# Enter docker container |
| 89 | +docker exec -it fpc-development-main /bin/bash |
| 90 | +cd samples/chaincode/confidential-escrow |
| 91 | + |
| 92 | +# Interactive menu |
| 93 | +./multi_user_dashboard.sh |
| 94 | + |
| 95 | +# Setup Alice using Option 3. |
| 96 | +``` |
| 97 | + |
| 98 | +#### 3. In 3rd terminal window - Docker Environment (`Bob`) |
| 99 | + |
| 100 | +```bash |
| 101 | +# Enter docker container |
| 102 | +docker exec -it fpc-development-main /bin/bash |
| 103 | +cd samples/chaincode/confidential-escrow |
| 104 | + |
| 105 | +# Interactive menu |
| 106 | +./multi_user_dashboard.sh |
| 107 | + |
| 108 | +# Setup Bob using Option 4. |
| 109 | +``` |
| 110 | + |
| 111 | +#### 4. In 4th terminal window - Docker Environment (`Monitor`) |
| 112 | + |
| 113 | +```bash |
| 114 | +# Enter docker container |
| 115 | +docker exec -it fpc-development-main /bin/bash |
| 116 | +cd samples/chaincode/confidential-escrow |
| 117 | + |
| 118 | +# Interactive menu |
| 119 | +./multi_user_dashboard.sh |
| 120 | + |
| 121 | +# Setup Monitor using Option 5. |
| 122 | +``` |
| 123 | + |
| 124 | +#### 5. Run Tests |
| 125 | + |
| 126 | +```bash |
| 127 | +# Run all basic tests |
| 128 | +./multi_user_dashboard.sh |
| 129 | + |
| 130 | +# Chosing Option 7. (One can run it from any terminal) |
| 131 | +``` |
| 132 | + |
| 133 | +## Escrow Workflow |
| 134 | + |
| 135 | +### Step 1: Create Wallets |
| 136 | + |
| 137 | +Before any escrow operations, both parties must have wallets: |
| 138 | + |
| 139 | +1. **Alice** creates her wallet via Terminal 2 (Option 3 - currently created automatically) |
| 140 | +2. **Bob** creates his wallet via Terminal 3 (Option 4 - currently created automatically) |
| 141 | +3. **Monitor** (Terminal 4, Option 5) can observe all wallet creations and transactions in real-time |
| 142 | + |
| 143 | +### Step 2: Create Escrow |
| 144 | + |
| 145 | +Once both wallets exist, either party can create an escrow using `createAndLockEscrow`. The buyer locks funds by specifying: |
| 146 | + |
| 147 | +- Buyer/seller public keys |
| 148 | +- Amount and asset type |
| 149 | +- `parcelId` and `secret` (used for condition verification) |
| 150 | + |
| 151 | +### Step 3: Complete Escrow |
| 152 | + |
| 153 | +Two possible outcomes: |
| 154 | + |
| 155 | +| Operation | Who Calls | When | Result | |
| 156 | +| ----------- | --------- | ------------------------------------------- | ------------------------ | |
| 157 | +| **Release** | Seller | Condition fulfilled (e.g., goods delivered) | Funds transfer to seller | |
| 158 | +| **Refund** | Buyer | Condition not met or cancelled | Funds return to buyer | |
| 159 | + |
| 160 | +### Release vs Refund |
| 161 | + |
| 162 | +- **Release** (`releaseEscrow`): Seller provides correct `secret + parcelId` to prove fulfillment. Funds move from buyer's escrow balance to seller's available balance. Status → `Released`. |
| 163 | + |
| 164 | +- **Refund** (`refundEscrow`): Buyer cancels an active escrow. No secret needed. Funds return to buyer's available balance. Status → `Refunded`. |
| 165 | + |
| 166 | +Both operations only work on `Active` escrows. |
| 167 | + |
| 168 | +## Troubleshooting |
| 169 | + |
| 170 | +**Network already running?** |
| 171 | +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: |
| 172 | + |
| 173 | +```bash |
| 174 | +# In test.sh, comment these lines: |
| 175 | +# run_cmd "./network.sh down" "Bringing down network" |
| 176 | +# run_cmd "./network.sh up createChannel -ca" "Starting network" |
| 177 | +``` |
| 178 | + |
| 179 | +## Contributing |
| 180 | + |
| 181 | +When adding new features: |
| 182 | + |
| 183 | +1. Define asset types in `chaincode/assets/` |
| 184 | +2. Implement transaction logic in `chaincode/transactions/` |
| 185 | +3. Register new components in `chaincode/setup.go` |
| 186 | +4. Add test cases to `main.sh` |
| 187 | +5. Update this README with usage examples |
0 commit comments