VeilShield

VeilShield is a Fhenix CoFHE project on Arbitrum Sepolia.

Confidential cargo delay cover for exporters: delay thresholds, claim logic, and role-scoped policy views stay private on-chain.

The trigger path runs on encrypted state on-chain. Token settlement still uses a plain ERC-20 test asset, and the contract mirrors the token terms into encrypted handles where the privacy logic needs them.

Built for the Fhenix Privacy-by-Design dApp Buildathon on AKINDO WaveHack: https://app.akindo.io/wave-hacks/Nm2qjzEBgCqJD90W?tab=overview

Live app: https://veilshield.xyz

Project standard

AI-assisted tools are fine in this repo. What is not fine is fake depth: code or copy that looks sophisticated but falls apart under inspection.

The bar here is straightforward:

• live contracts over mock animations
• explicit tradeoffs over vague privacy claims
• tests and deployable flows over surface-level complexity
• deliberate design choices over autogenerated noise

What's in the repo

• contracts/VeilShield.sol: the main contract
• contracts/VeilShieldDemoToken.sol: the token used for premiums, LP deposits, and payouts
• veilshield-app.jsx: the frontend entry point
• scripts/deploy.ts: deploys both contracts and writes deployment metadata
• deployments/arb-sepolia.json: the current Arbitrum Sepolia deployment

Quick framing

VeilShield is not trying to hide every field on-chain.

It hides the parts that matter for this use case:

• shipment delay threshold
• encrypted oracle reading
• encrypted payout selection
• user-scoped LP and policy views

And it keeps the parts that still need visible token settlement public:

• coverage amount
• premium amount
• beneficiary
• expiry
• pool token accounting

That boundary is deliberate. It is written down in the docs instead of implied by marketing copy.

Docs for judges

• ARCHITECTURE.md: contract, frontend, and live network layout
• PRIVACY_MODEL.md: what is encrypted, what is public, and who can decrypt what
• DEMO_FLOW.md: the fastest live demo path for a judge or video recording
• WAVES.md: what shipped, what is rough, and what the next steps are

What the demo does

• encrypted LP accounting with CoFHE handles
• encrypted oracle submissions
• trigger checks with FHE.gte and FHE.lte
• conditional routing with FHE.select
• async finalization through FHE.decrypt
• ERC-20 deposit, premium, and payout flow with vUSD
• role-based workspaces for policy holder, LP, oracle / claims, and auditor
• explicit permit-based selective disclosure flow in the frontend
• seeded exporter demo path for a non-empty live first screen

Why this fits the buildathon

• runs on a live supported testnet: Arbitrum Sepolia
• keeps part of the core protocol state encrypted during computation instead of exposing it in plaintext
• does real smart-contract evaluation with CoFHE rather than a frontend-only privacy simulation
• documents the privacy boundary in plain terms, including what is still public
• ships as a working demo with verified contracts, tests, and a live frontend

Live deployment

• Network: Arbitrum Sepolia
• VeilShield: 0x42Fd32Fa18975D5A2Ba57bb0e86682aE9dEb13Da
• vUSD: 0x8D58098D3B2Cbef4c5fa1CFef38A0baD7Ef81C70
• Oracle: 0x4eD3265fA5217071F678eCD58eAf7f720dBf3FEc
• VeilShield on Arbiscan: 0x42Fd32Fa18975D5A2Ba57bb0e86682aE9dEb13Da
• vUSD on Arbiscan: 0x8D58098D3B2Cbef4c5fa1CFef38A0baD7Ef81C70

The deployment file is in deployments/arb-sepolia.json.

Current seeded state on the new deployment:

• one active exporter policy is live
• two policies are currently in PendingDecision
• one fallback policy is already in Cancelled, so public claim history is not empty
• pool liquidity and encrypted handles are non-empty
• the remaining pending rows depend on the live threshold network returning async decrypt results

Product framing

The current wedge is exporters buying cargo / shipment delay cover.

Why this use case fits privacy-by-design:

• exporters do not want to reveal delay thresholds that expose operating tolerance
• coverage sizes can leak shipment value or treasury posture
• claims history is useful publicly, but policy terms should stay role-scoped
• LPs and auditors need controlled disclosure, not blanket transparency

Run locally

npm install
npm run compile
npm test
npm run build

Start the frontend with:

npm run dev

You need a browser wallet such as MetaMask. The app will ask to switch to Arbitrum Sepolia.

Environment

Create .env from .env.example and fill in at least:

PRIVATE_KEY=0x...

Optional:

ARBITRUM_SEPOLIA_RPC_URL=https://...
ORACLE_ADDRESS=0x...
ETHERSCAN_API_KEY=...

If ORACLE_ADDRESS is missing, deploy falls back to the deployer wallet.

Deploy

npm run deploy:arb-sepolia

This deploys:

• VeilShieldDemoToken
• VeilShield(oracle, asset)

Verify with:

npm run verify:arb-sepolia

Seed the live exporter scenario with:

npm run seed:arb-sepolia

If the threshold network is slow, the seeded state may keep one or more policies in PendingDecision until the async decrypt result arrives.

Demo flow

1. Connect a wallet on Arbitrum Sepolia.
2. Mint vUSD in the pool screen.
3. Approve vUSD once.
4. Deposit liquidity.
5. Create a cargo delay policy with an encrypted threshold and encrypted mirrors of the token terms.
6. Submit an encrypted oracle reading from the oracle wallet.
7. Request evaluation.
8. Wait a few seconds while the threshold network finishes the decision.
9. Finalize the result.
10. Settle the payout if the policy triggered.
11. Use permit-based local decrypt for policy holder, beneficiary, LP, or auditor views.

Notes

• Tests are written against the local CoFHE mock setup.
• The frontend is still demo-oriented, but now includes role workspaces, permit status, and async claim polling.
• Node 20 or 22 is safer with Hardhat than Node 25.
• The repo is fine to build with AI assistance, but every feature should still be defensible in code, tests, and runtime behavior.