ShieldFlow is a confidential escrow and milestone payment protocol built on Zama fhEVM. Encrypted amounts, programmable milestones, and selective auditor access — all enforced on-chain without revealing values to the network.
ShieldFlow solves a fundamental problem in on-chain escrow: every ETH amount and milestone condition is publicly visible on-chain by default, exposing deal terms to competitors, regulators, and adversaries before work is even complete.
By building on Zama's Fully Homomorphic Encryption (FHE) virtual machine, ShieldFlow keeps every payment amount encrypted at the smart contract layer. Counterparties see that funds exist, but the amounts remain sealed — the blockchain cannot read them, and neither can any third party unless explicitly granted access via on-chain ACL.
All amounts stored as euint64 ciphertexts. Plain values never appear in contract state.
Client, Contractor, and optional Auditor each get precisely scoped on-chain access.
Built on fhEVM standards — ACL handles interoperate with other Zama-native contracts.
Escrows move through six on-chain steps. FHE operations happen at deposit and release — the two moments where financial values are read or updated.
createEscrow()caller: Client→ PendingRegister contractor, optional auditor, and milestone deadlines. No ETH yet.
deposit()caller: Client→ ActiveFHESend ETH + FHE-encrypted amounts for each milestone. Amounts are sealed on-chain.
submitMilestone()caller: Contractor→ InProgressMark a milestone as complete and ready for review.
approveMilestone()caller: Client→ ApprovedVerify deliverables and mark the milestone approved.
releaseMilestone()caller: Client→ ReleasedFHETrigger FHE homomorphic add to update encrypted running total. Payment queued.
withdrawReleased()caller: Contractor→ CompletedPull accrued ETH to wallet. Escrow completes when all milestones are released.
Create — Only addresses are public. Milestone count is visible; amounts are not set yet.
Deposit — ETH value in msg.value is visible; the breakdown across milestones is hidden inside euint64 handles. Only permissioned parties can request decryption.
Submit → Approve — Status flags are public. No amounts change; privacy unchanged.
Release — Homomorphic addition updates encrypted releasedAmount. The release transaction includes amountWei for native ETH (public in that tx); the full milestone schedule stays encrypted until each release.
Withdraw — ETH transfer is on-chain; individual milestone allocations remain hidden in ciphertext.
msg.value) appears in the EscrowDeposited event. Per-milestone allocations are never revealed on-chain unless an authorised party requests FHE decryption through the relayer.Every monetary value — total deposit and per-milestone allocation — is stored as a euint64 ciphertext on Zama fhEVM. No smart contract, indexer, or blockchain explorer can read these values without explicit ACL permission. The escrow enforces correct payment ordering purely through FHE arithmetic.
Three roles with scoped privileges. The Client controls flow (create, deposit, approve, release). The Contractor submits milestones and withdraws. The Auditor gains read-only FHE access granted by the Client at any point during the escrow lifecycle — without disrupting the payment flow.
Up to 10 milestones per escrow, each with an independent encrypted amount and deadline. Release uses FHE.select to guard against overflow — the running releasedAmount accumulates homomorphically and is only trusted if the operation succeeds. Milestones flow through: Pending → InProgress → Approved → Released.
grantAuditorAccess() issues on-chain FHE.allow() calls for every encrypted handle in the escrow — total deposit, released total, and each milestone amount. This enables a compliance workflow where an auditor can prove payment occurred without parties having to reveal deal terms to the public.
ShieldFlow uses FHE.allowThis() so the contract can re-read its own ciphertexts in future transactions. ACL handles are standard fhEVM objects compatible with ERC-7984 and other Zama-native contracts. The pattern can be extended to support token-gated access, DAO governance, or automated oracle-triggered releases.
Fully Homomorphic Encryption allows arbitrary computation on ciphertexts without decrypting them first. Zama fhEVM implements this at the EVM level using the TFHE cryptosystem, enabling Solidity contracts to add, compare, and branch on encrypted integers.
euint64 terms). Settlement uses public ETH rails — deposit msg.value, release amountWei, and withdraw transfers are visible by Ethereum design. We do not claim full payment privacy.| Solidity type | Used for | ABI encoding |
|---|---|---|
| euint64 | Milestone amounts, total deposit, released total (all in Gwei) | bytes32 handle |
| externalEuint64 | User-submitted ciphertexts (before conversion with FHE.fromExternal) | bytes32 |
| ebool | Encrypted boolean for overflow guard in releaseMilestone | bytes32 handle |
Users encrypt values client-side with the Zama relayer SDK before submitting. FHE.fromExternal() converts the user-submitted ciphertext and zero-knowledge input proof into an euint64 that the contract can operate on. ACL calls immediately follow to register who may decrypt each handle.
euint64 encTotal = FHE.fromExternal(encryptedTotal, inputProof);
euint64 sumMilestones = FHE.asEuint64(0);
for (uint8 i = 0; i < e.milestoneCount; i++) {
euint64 amt = FHE.fromExternal(encMilestoneAmts[i], inputProof);
sumMilestones = FHE.add(sumMilestones, amt);
e.milestones[i].encryptedAmount = amt;
FHE.allowThis(e.milestones[i].encryptedAmount);
FHE.allow(e.milestones[i].encryptedAmount, msg.sender);
FHE.allow(e.milestones[i].encryptedAmount, e.contractor);
}
FHE.eq(encTotal, sumMilestones);
FHE.eq(sumMilestones, FHE.asEuint64(uint64(msg.value)));
e.totalDeposit = sumMilestones;releaseMilestone() uses FHE.add() to accumulate the released total homomorphically — the contract never decrypts the value. To guard against 64-bit overflow, FHE.select() acts as an encrypted ternary: if overflow is detected (the result is less than the previous value), the old value is preserved.
// Homomorphic addition — both operands remain encrypted
euint64 newReleased = FHE.add(e.releasedAmount, m.encryptedAmount);
// Overflow guard: compare encrypted values without revealing them
ebool didOverflow = FHE.lt(newReleased, e.releasedAmount);
// FHE.select(cond, ifTrue, ifFalse) — branch without decrypting
// If overflow detected: keep old value. Otherwise: accept newReleased.
e.releasedAmount = FHE.select(didOverflow, e.releasedAmount, newReleased);
// Re-issue ACL after mutation so all parties retain read access
FHE.allowThis(e.releasedAmount);
FHE.allow(e.releasedAmount, e.client);
FHE.allow(e.releasedAmount, e.contractor);
if (e.auditor != address(0)) {
FHE.allow(e.releasedAmount, e.auditor);
}The Access Control List (ACL) is Zama fhEVM's mechanism for granting decryption rights. Every ciphertext handle exists in an on-chain ACL registry. When a user requests decryption through the Zama relayer, the relayer verifies the caller holds an ACL grant before returning the plaintext. No grant — no decryption.
function grantAuditorAccess(uint256 escrowId, address auditor)
external onlyClient(escrowId)
{
require(auditor != address(0), "ShieldFlow: invalid auditor address");
Escrow storage e = _escrows[escrowId];
e.auditor = auditor;
// Issue ACL grants for every encrypted handle in the escrow
FHE.allow(e.totalDeposit, auditor);
FHE.allow(e.releasedAmount, auditor);
for (uint8 i = 0; i < e.milestoneCount; i++) {
if (FHE.isInitialized(e.milestones[i].encryptedAmount)) {
FHE.allow(e.milestones[i].encryptedAmount, auditor);
}
}
emit AuditorGranted(escrowId, auditor);
}The frontend encrypts ETH amounts Gwei before submitting them to the contract. The SDK generates a batched ZK input proof covering all values in a single call, which is passed as inputProof to deposit().
import { createInstance } from "@zama-fhe/relayer-sdk";
// Initialise the fhEVM instance for the connected wallet
const instance = await createInstance({
kmsContractAddress, // Zama KMS contract on Sepolia
aclContractAddress, // Zama ACL contract on Sepolia
network: provider,
});
// Build a batched input — all values share one proof
const input = instance.createEncryptedInput(contractAddress, userAddress);
input.add64(totalGwei); // Encrypted total
input.add64(milestone1Gwei); // Per-milestone breakdown
input.add64(milestone2Gwei);
const { handles, inputProof } = await input.encrypt();
// handles[0] = encryptedTotal (externalEuint64)
// handles[1], handles[2] = encMilestoneAmts[]
// inputProof = ZK proof the client knows the plaintexts
await deposit(escrowId, handles[0], [handles[1], handles[2]], inputProof, amountsWei);inputProof is a compact zero-knowledge proof generated by the Zama SDK that proves the user supplied well-formed 64-bit values. Without it, FHE.fromExternal() would revert. This prevents malformed ciphertext attacks that could corrupt encrypted state.| Property | Centralized | ZK Proofs | FHE — ShieldFlow |
|---|---|---|---|
| On-chain privacy | ✗ Amounts public | ⚡ Partial (proofs only) | ✓ Full encryption |
| Compute on secrets | ✗ Raw data required | ✗ Prove, not compute | ✓ Homomorphic ops |
| Trustless execution | ✗ Custodian required | ✓ Verifiable | ✓ On-chain, no trust |
| Custodial risk | High — single party holds funds | None | None — smart contract |
| Programmable conditions | Manual / off-chain | Complex circuit design | ✓ FHE.select, FHE.add |
| Selective disclosure | All-or-nothing | Difficult; verifier set | ✓ Per-address ACL |
| Auditability | Off-chain only | Proof logs | ✓ On-chain ACL grants |
Step-by-step instructions for each role in a ShieldFlow escrow.
The Client creates and funds the escrow, approves completed milestones, and releases payments.
Contractors receive an escrow link from the client. No wallet connection is needed to view the invite; a Sepolia wallet is required to interact.
Auditors have read-only decryption access. They cannot approve, release, or withdraw. Their role is to verify that payment amounts match agreed terms for compliance purposes.
onlyClient and onlyContractor modifiers enforce this at the contract level.| Function | Caller | Description |
|---|---|---|
| createEscrow() | Client | Registers a new escrow in Pending state. Sets parties and milestone deadlines. Returns escrowId. |
| deposit() | Client | Funds the escrow with ETH (msg.value is public). Accepts FHE-encrypted total and per-milestone amounts in one inputProof batch. Homomorphic FHE.eq validates milestone sum. No plaintext milestone array on-chain. |
| submitMilestone() | Contractor | Marks a milestone as submitted (InProgress). Signals work is ready for client review. |
| approveMilestone() | Client | Approves a submitted milestone, setting status to Approved and enabling release. |
| releaseMilestone() | Client | Releases payment for an approved milestone. Updates encrypted running total homomorphically. amountWei is used for native ETH accounting (visible in this tx only — not stored in public getters/events). |
| openDispute() | Client or Contractor | Opens a dispute on a submitted/approved milestone. Freezes release and withdraw until auditor resolves. |
| resolveDispute() | Auditor | Resolves a dispute: Release (queue ETH for contractor) or Refund (return ETH to client). Auditor decrypts confidential terms off-chain to adjudicate. |
| withdrawReleased() | Contractor | Transfers all queued ETH (from released milestones) to the contractor's wallet. |
| grantAuditorAccess() | Client | Adds an auditor address and grants FHE ACL read access to all encrypted handles in the escrow. |
| cancelEscrow() | Client | Cancels a Pending (unfunded) escrow. Cannot cancel after deposit. |
| getEscrowInfo() | Anyone | Returns parties, status, creation timestamp, and milestone count. |
| getPendingWithdrawal() | Anyone | Returns operational pending withdrawal wei for the contractor queue. Does not expose per-milestone splits. |
| getTotalDeposit() | ACL holders | Returns the euint64 handle for the encrypted total deposit. Requires FHE ACL permission to decrypt. |
| getMilestone() | ACL holders | Returns milestone data including encrypted amount handle, deadline, and status flags. |
| Event | Description |
|---|---|
| EscrowCreated | Fired on successful createEscrow() |
| EscrowDeposited | Fired after deposit confirms — no wei amounts in event |
| MilestoneSubmitted | Contractor submitted a milestone |
| MilestoneApproved | Client approved a submitted milestone |
| MilestoneReleased | Payment released for a milestone — no amountWei |
| FundsWithdrawn | Contractor withdrew ETH — no amountWei |
| DisputeOpened | Dispute opened by client or contractor |
| DisputeResolved | Auditor resolved dispute |
| EscrowCompleted | All milestones released; escrow fully settled |
| EscrowCancelled | Pending escrow cancelled by client |
| AuditorGranted | Auditor ACL access granted |
Every ciphertext handle created or modified by ShieldFlowEscrow immediately receives ACL grants via FHE.allowThis() and role-specific FHE.allow(). Without FHE.allowThis(), the contract cannot re-read its own ciphertexts in future transactions — a common fhEVM mistake that would permanently freeze state.
FHE operations are significantly more gas-expensive than plaintext arithmetic on standard EVM chains. On Zama fhEVM Sepolia, each FHE.add, FHE.lt, and FHE.selectcarries an overhead computed by Zama's coprocessor. As a result:
deposit() gas usage (10 FHE.fromExternal calls).releaseMilestone() performs 3 FHE ops (add, lt, select) per call — plan milestone granularity accordingly.grantAuditorAccess() gas scales linearly with milestone count (one FHE.allow per milestone).msg.value is public (native ETH). Per-milestone splits remain in encrypted handles only.# 1. Clone and install
git clone https://github.com/your-org/shieldflow
cd shieldflow/fhevm-hardhat
pnpm install
# 2. Configure environment
cp .env.example .env
# Set PRIVATE_KEY and ALCHEMY_API_KEY in .env
# 3. Deploy to Sepolia
npx hardhat run deploy/deploy_ShieldFlowEscrow.ts --network sepolia
# Output: ShieldFlowEscrow deployed to: 0x...
# Update frontend/src/lib/contracts/addresses.ts with the new addresscd frontend
pnpm install
cp .env.local.example .env.local| Variable | Description |
|---|---|
| NEXT_PUBLIC_ALCHEMY_RPC_URL | Alchemy RPC endpoint for Sepolia (or any Sepolia-compatible RPC) |
| NEXT_PUBLIC_CHAIN_ID | 11155111 for Sepolia |
After redeploying, update the address in:
export const CONTRACT_ADDRESSES = {
sepolia: {
ShieldFlowEscrow: "0xYOUR_NEW_ADDRESS" as `0x${string}`,
},
} as const;ShieldFlow uses the Zama hosted relayer on Sepolia. The relayer is initialized in src/lib/fhe/fhevm.ts using the public Zama KMS and ACL contract addresses for Sepolia. No API key is required for testnet usage. For production deployments, consult Zama fhEVM documentation for relayer configuration options.
ShieldFlow is actively developed. The following capabilities are planned for future releases.