create-shield-unshield-dapp 1.0.1

package/README.md

@@ -0,0 +1,31 @@
+# create-shield-unshield-dapp
+
+Scaffold a **Shield/Unshield dApp** for wrapping and unwrapping USDC ↔ cUSDC and USDT ↔ cUSDT, and for confidential transfers. Uses ERC-7984 confidential tokens and the Zama relayer.
+
+## Install and run
+
+```bash
+npx create-shield-unshield-dapp my-app
+cd my-app
+cp .env.example .env
+# Edit .env (see below)
+npm run dev
+```
+
+Open the URL shown (e.g. http://localhost:5173) and connect your wallet.
+
+## Switching environment (mainnet vs testnet)
+
+- **Mainnet:** In `.env` set `VITE_MAINNET=true`. Contract addresses are built-in. Optionally set `VITE_MAINNET_RPC_URL`. Connect your wallet to Ethereum Mainnet.
+- **Testnet (Sepolia):** Leave `VITE_MAINNET=false` or omit it. Set the four Sepolia contract addresses in `.env`: `VITE_USDC_ADDRESS`, `VITE_CONF_USDC_ADDRESS`, `VITE_USDT_ADDRESS`, `VITE_CONF_USDT_ADDRESS`. Connect your wallet to Sepolia.
+
+Full details, all environment variables, and where to get Sepolia addresses are in the **scaffolded project’s README** (`README.md` in the created folder).
+
+## Options
+
+- `npx create-shield-unshield-dapp my-app --force` — Overwrite existing files in `my-app` if it already exists.
+- `npx create-shield-unshield-dapp my-app --no-install` — Skip running `npm install` after copying (run it yourself).
+
+## License
+
+MIT.

package/bin/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force') || args.includes('-f');
+  const noInstall = args.includes('--no-install');
+  const target = args.find((a) => !a.startsWith('-')) || 'shield-unshield-app';
+  return { target, force, noInstall };
+}
+
+function copyRecursive(src, dest, force) {
+  if (!fs.existsSync(src)) {
+    console.error('Template not found at', src);
+    process.exit(1);
+  }
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry), force);
+    }
+  } else {
+    if (fs.existsSync(dest) && !force) return;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function main() {
+  const { target, force, noInstall } = parseArgs();
+  const targetPath = path.resolve(process.cwd(), target);
+
+  if (fs.existsSync(targetPath) && fs.readdirSync(targetPath).length > 0 && !force) {
+    console.error(`Directory "${target}" already exists and is not empty. Use --force to overwrite.`);
+    process.exit(1);
+  }
+
+  console.log('Creating Shield/Unshield dApp in', targetPath);
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+  }
+  copyRecursive(TEMPLATE_DIR, targetPath, force);
+  console.log('Template copied.');
+
+  if (!noInstall) {
+    console.log('Running npm install...');
+    try {
+      execSync('npm install', { cwd: targetPath, stdio: 'inherit' });
+    } catch (e) {
+      console.warn('npm install failed. Run "npm install" in the project folder manually.');
+    }
+  }
+
+  console.log('\nDone! Next steps:\n');
+  console.log(`  cd ${target}`);
+  console.log('  cp .env.example .env');
+  console.log('  # Edit .env: set VITE_MAINNET=true for mainnet, or set Sepolia contract addresses for testnet.');
+  console.log('  # See README.md for full environment and mainnet/testnet docs.');
+  console.log('  npm run dev\n');
+}
+
+main();

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-shield-unshield-dapp",
+  "version": "1.0.1",
+  "description": "Scaffold a Shield/Unshield dApp for USDC/cUSDC and USDT/cUSDT (wrap, unwrap, confidential transfer)",
+  "type": "commonjs",
+  "bin": {
+    "create-shield-unshield-dapp": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "scripts": {
+    "copy-template": "node scripts/copy-template.js"
+  },
+  "keywords": [
+    "shield",
+    "unshield",
+    "confidential",
+    "usdc",
+    "usdt",
+    "erc-7984",
+    "zama"
+  ],
+  "license": "MIT"
+}

package/template/.env.example

@@ -0,0 +1,16 @@
+# Network: "true" = Ethereum Mainnet, anything else (or unset) = Sepolia testnet
+VITE_MAINNET=false
+
+# ---- Testnet (Sepolia) ----
+VITE_SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
+VITE_USDC_ADDRESS=0x...
+VITE_CONF_USDC_ADDRESS=0x...
+VITE_USDT_ADDRESS=0x...
+VITE_CONF_USDT_ADDRESS=0x...
+
+# ---- Mainnet (only when VITE_MAINNET=true) ----
+# Mainnet contract addresses are built-in. Optional: custom RPC
+# VITE_MAINNET_RPC_URL=https://eth.llamarpc.com
+
+# WalletConnect project ID (optional)
+# VITE_WALLETCONNECT_PROJECT_ID=your_project_id

package/template/README.md

@@ -0,0 +1,91 @@
+# Shield / Unshield dApp
+
+A frontend for wrapping and unwrapping **USDC ↔ cUSDC** and **USDT ↔ cUSDT**, and for **transferring** confidential tokens. Supports **Ethereum Mainnet** and **Sepolia** testnet. Uses ERC-7984 confidential token contracts and the Zama relayer for unwrap decryption.
+
+## Features
+
+- **Wrap (shield):** USDC → cUSDC, USDT → cUSDT.
+- **Unwrap (unshield):** cUSDC → USDC, cUSDT → USDT (two-step flow via Zama gateway).
+- **Transfer:** Send cUSDC or cUSDT to any address; amount is encrypted on-chain.
+
+## Prerequisites
+
+- Node.js 18+
+- A wallet (e.g. MetaMask) on the network you use (Mainnet or Sepolia).
+
+## Quick start
+
+1. Install dependencies (if not already done):
+
+   ```bash
+   npm install
+   ```
+
+2. Copy the example env file and edit it:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+3. Configure for your target network:
+   - **Testnet (Sepolia):** Set the four contract addresses in `.env` (see [Environment variables](#environment-variables)).
+   - **Mainnet:** Set only `VITE_MAINNET=true` in `.env`; contract addresses are built-in.
+
+4. Run the app:
+
+   ```bash
+   npm run dev
+   ```
+
+5. Open the URL (e.g. http://localhost:5173), connect your wallet to the correct network (Sepolia or Mainnet), and use the app.
+
+## Switching environment (mainnet vs testnet)
+
+The app uses a single env flag to choose the network.
+
+| Mode     | Set in `.env`                     | Contract addresses |
+|----------|-----------------------------------|--------------------|
+| Testnet  | `VITE_MAINNET=false` or omit      | **Required:** `VITE_USDC_ADDRESS`, `VITE_CONF_USDC_ADDRESS`, `VITE_USDT_ADDRESS`, `VITE_CONF_USDT_ADDRESS` (Sepolia). |
+| Mainnet  | `VITE_MAINNET=true`               | **Built-in.** No address env vars needed. Optional: `VITE_MAINNET_RPC_URL`. |
+
+- **After changing** `.env`, restart the dev server (`npm run dev`) or rebuild for production (`npm run build`).
+- **Mainnet:** Wrap and transfer work with built-in addresses. Unwrap/decrypt on mainnet may require a relayer API key (contact the Zama team for access).
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `VITE_MAINNET` | No | Set to `"true"` for Ethereum Mainnet; anything else or unset = Sepolia testnet. |
+| `VITE_SEPOLIA_RPC_URL` | No | Sepolia RPC URL (default: public node). |
+| `VITE_USDC_ADDRESS` | Yes (testnet) | USDC (underlying) contract on Sepolia. |
+| `VITE_CONF_USDC_ADDRESS` | Yes (testnet) | cUSDC (wrapper) contract on Sepolia. |
+| `VITE_USDT_ADDRESS` | Yes (testnet) | USDT (underlying) contract on Sepolia. |
+| `VITE_CONF_USDT_ADDRESS` | Yes (testnet) | cUSDT (wrapper) contract on Sepolia. |
+| `VITE_MAINNET_RPC_URL` | No | Mainnet RPC URL when `VITE_MAINNET=true` (default: public RPC). |
+| `VITE_WALLETCONNECT_PROJECT_ID` | No | WalletConnect project ID (optional). |
+
+## Where to get Sepolia addresses
+
+Obtain the USDC, cUSDC, USDT, and cUSDT contract addresses from your deployment or from the Zama/contract documentation. The app does not ship valid default addresses for Sepolia.
+
+## Build and preview
+
+```bash
+npm run build
+```
+
+Output is in `dist/`. To serve it locally:
+
+```bash
+npm run preview
+```
+
+## Architecture
+
+- **Frontend only:** No backend or indexer; reads from the chain and uses the Zama relayer for unwrap decryption proof.
+- **Contracts:** ERC-7984 confidential token wrappers with `wrap`, `unwrap`, `finalizeUnwrap`, and `confidentialTransfer`.
+- **Two token pairs:** USDC/cUSDC and USDT/cUSDT; on testnet you supply all four addresses via env; on mainnet they are built-in.
+
+## License
+
+MIT.

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Shield / Unshield dApp</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "shield-unshield-dapp",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "call-bound": "^1.0.2",
+    "es-errors": "^1.3.0",
+    "is-typed-array": "^1.1.13",
+    "@rainbow-me/rainbowkit": "^2.2.10",
+    "@tanstack/react-query": "^5.90.12",
+    "@tailwindcss/vite": "^4.1.18",
+    "@zama-fhe/relayer-sdk": "^0.3.0-8",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.562.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-hot-toast": "^2.6.0",
+    "react-router-dom": "^7.11.0",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss": "^4.1.18",
+    "viem": "^2.43.2",
+    "wagmi": "^2.19.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "7.2.4"
+  }
+}

package/template/public/usdc.svg

@@ -0,0 +1,5 @@
+<svg data-name="86977684-12db-4850-8f30-233a7c267d11" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2000 2000">
+  <path d="M1000 2000c554.17 0 1000-445.83 1000-1000S1554.17 0 1000 0 0 445.83 0 1000s445.83 1000 1000 1000z" fill="#2775ca"/>
+  <path d="M1275 1158.33c0-145.83-87.5-195.83-262.5-216.66-125-16.67-150-50-150-108.34s41.67-95.83 125-95.83c75 0 116.67 25 137.5 87.5 4.17 12.5 16.67 20.83 29.17 20.83h66.66c16.67 0 29.17-12.5 29.17-29.16v-4.17c-16.67-91.67-91.67-162.5-187.5-170.83v-100c0-16.67-12.5-29.17-33.33-33.34h-62.5c-16.67 0-29.17 12.5-33.34 33.34v95.83c-125 16.67-204.16 100-204.16 204.17 0 137.5 83.33 191.66 258.33 212.5 116.67 20.83 154.17 45.83 154.17 112.5s-58.34 112.5-137.5 112.5c-108.34 0-145.84-45.84-158.34-108.34-4.16-16.66-16.66-25-29.16-25h-70.84c-16.66 0-29.16 12.5-29.16 29.17v4.17c16.66 104.16 83.33 179.16 220.83 200v100c0 16.66 12.5 29.16 33.33 33.33h62.5c16.67 0 29.17-12.5 33.34-33.33v-100c125-20.84 208.33-108.34 208.33-220.84z" fill="#fff"/>
+  <path d="M787.5 1595.83c-325-116.66-491.67-479.16-370.83-800 62.5-175 200-308.33 370.83-370.83 16.67-8.33 25-20.83 25-41.67V325c0-16.67-8.33-29.17-25-33.33-4.17 0-12.5 0-16.67 4.16-395.83 125-612.5 545.84-487.5 941.67 75 233.33 254.17 412.5 487.5 487.5 16.67 8.33 33.34 0 37.5-16.67 4.17-4.16 4.17-8.33 4.17-16.66v-58.34c0-12.5-12.5-29.16-25-37.5zM1229.17 295.83c-16.67-8.33-33.34 0-37.5 16.67-4.17 4.17-4.17 8.33-4.17 16.67v58.33c0 16.67 12.5 33.33 25 41.67 325 116.66 491.67 479.16 370.83 800-62.5 175-200 308.33-370.83 370.83-16.67 8.33-25 20.83-25 41.67V1700c0 16.67 8.33 29.17 25 33.33 4.17 0 12.5 0 16.67-4.16 395.83-125 612.5-545.84 487.5-941.67-75-237.5-258.34-416.67-487.5-491.67z" fill="#fff"/>
+</svg>

package/template/public/usdt.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 339.43 295.27"><title>tether-usdt-logo</title><path d="M62.15,1.45l-61.89,130a2.52,2.52,0,0,0,.54,2.94L167.95,294.56a2.55,2.55,0,0,0,3.53,0L338.63,134.4a2.52,2.52,0,0,0,.54-2.94l-61.89-130A2.5,2.5,0,0,0,275,0H64.45a2.5,2.5,0,0,0-2.3,1.45h0Z" style="fill:#50af95;fill-rule:evenodd"/><path d="M191.19,144.8v0c-1.2.09-7.4,0.46-21.23,0.46-11,0-18.81-.33-21.55-0.46v0c-42.51-1.87-74.24-9.27-74.24-18.13s31.73-16.25,74.24-18.15v28.91c2.78,0.2,10.74.67,21.74,0.67,13.2,0,19.81-.55,21-0.66v-28.9c42.42,1.89,74.08,9.29,74.08,18.13s-31.65,16.24-74.08,18.12h0Zm0-39.25V79.68h59.2V40.23H89.21V79.68H148.4v25.86c-48.11,2.21-84.29,11.74-84.29,23.16s36.18,20.94,84.29,23.16v82.9h42.78V151.83c48-2.21,84.12-11.73,84.12-23.14s-36.09-20.93-84.12-23.15h0Zm0,0h0Z" style="fill:#fff;fill-rule:evenodd"/></svg>

package/template/src/App.tsx

@@ -0,0 +1,6 @@
+import React from 'react';
+import { ShieldUnshieldPage } from './pages/ShieldUnshieldPage';
+
+export default function App() {
+  return <ShieldUnshieldPage />;
+}

package/template/src/components/ui/Badge.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+import { cn } from '../../lib/utils';
+
+interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error';
+  size?: 'sm' | 'md';
+}
+
+export function Badge({ className, variant = 'default', size = 'sm', children, ...props }: BadgeProps) {
+  const base = 'inline-flex items-center font-bold rounded-full';
+  const sizes: Record<string, string> = {
+    sm: 'px-2.5 py-0.5 text-[11px]',
+    md: 'px-3 py-1 text-xs',
+  };
+  const variants: Record<string, string> = {
+    default: 'bg-[#f4eee6] text-[var(--color-text-primary)]',
+    primary: 'bg-[var(--color-primary)]/10 text-[var(--color-primary)]',
+    success: 'bg-[var(--color-success-bg)] text-emerald-700',
+    warning: 'bg-[var(--color-warning-bg)] text-amber-700',
+    error: 'bg-[var(--color-error-bg)] text-red-700',
+  };
+  return <span className={cn(base, sizes[size], variants[variant], className)} {...props}>{children}</span>;
+}

package/template/src/components/ui/Button.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { cn } from '../../lib/utils';
+
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'success';
+  size?: 'sm' | 'md' | 'lg';
+  loading?: boolean;
+}
+
+export function Button({
+  className,
+  variant = 'primary',
+  size = 'md',
+  loading = false,
+  disabled,
+  children,
+  ...props
+}: ButtonProps) {
+  const base =
+    'relative inline-flex items-center justify-center font-bold rounded-xl transition-all duration-200 cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed';
+  const sizes: Record<string, string> = {
+    sm: 'px-3 py-1.5 text-xs gap-1.5',
+    md: 'px-5 py-2.5 text-sm gap-2',
+    lg: 'px-7 py-3.5 text-base gap-2.5',
+  };
+  const variants: Record<string, string> = {
+    primary: 'bg-[var(--color-primary)] text-white shadow-lg hover:bg-orange-600 active:scale-[0.98] focus-visible:ring-[var(--color-primary)]',
+    secondary: 'border-2 border-[var(--color-border-light)] text-[var(--color-text-primary)] bg-white hover:bg-[#f4eee6] active:scale-[0.98] focus-visible:ring-[var(--color-primary)]',
+    ghost: 'text-[var(--color-text-primary)] hover:bg-[#f4eee6]',
+    danger: 'bg-[var(--color-error)] text-white hover:bg-red-600 active:scale-[0.98]',
+    success: 'bg-[var(--color-success)] text-white hover:bg-emerald-600 active:scale-[0.98]',
+  };
+
+  return (
+    <button className={cn(base, sizes[size], variants[variant], className)} disabled={disabled || loading} {...props}>
+      {loading && (
+        <svg className="animate-spin h-4 w-4" viewBox="0 0 24 24" fill="none">
+          <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+          <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+        </svg>
+      )}
+      {children}
+    </button>
+  );
+}

package/template/src/components/ui/Card.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import { cn } from '../../lib/utils';
+
+interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+  variant?: 'default' | 'elevated' | 'bordered';
+  padding?: 'sm' | 'md' | 'lg';
+}
+
+export function Card({ className, variant = 'default', padding = 'md', ...props }: CardProps) {
+  const base = 'rounded-xl transition-all duration-200';
+  const variants: Record<string, string> = {
+    default: 'bg-white border border-[var(--color-border-light)] shadow-sm',
+    elevated: 'bg-white border border-[var(--color-border-light)] shadow-sm hover:shadow-md',
+    bordered: 'bg-white border-2 border-[var(--color-border-light)]',
+  };
+  const paddings: Record<string, string> = {
+    sm: 'p-4',
+    md: 'p-6',
+    lg: 'p-8',
+  };
+  return <div className={cn(base, variants[variant], paddings[padding], className)} {...props} />;
+}

package/template/src/components/ui/Input.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { cn } from '../../lib/utils';
+
+interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  label?: string;
+  hint?: string;
+  error?: string;
+}
+
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, label, hint, error, ...props }, ref) => (
+    <div className="space-y-1.5">
+      {label && (
+        <label className="block text-xs font-semibold text-[var(--color-text-secondary)] uppercase tracking-wide">
+          {label}
+        </label>
+      )}
+      <input
+        ref={ref}
+        className={cn(
+          'w-full rounded-xl border bg-white px-4 py-2.5 text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-tertiary)]',
+          'border-[var(--color-border-input)] focus:outline-none focus:ring-2 focus:ring-[var(--color-primary)]/20 focus:border-[var(--color-primary)]',
+          error && 'border-[var(--color-error)]',
+          className
+        )}
+        {...props}
+      />
+      {hint && !error && <p className="text-[11px] text-[var(--color-text-tertiary)]">{hint}</p>}
+      {error && <p className="text-[11px] text-[var(--color-error)]">{error}</p>}
+    </div>
+  )
+);
+Input.displayName = 'Input';

package/template/src/hooks/useConfidentialBalance.ts

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useState } from 'react';
+import { createPublicClient, http } from 'viem';
+import { useAccount } from 'wagmi';
+import { CONF_TOKEN_ABI, CHAIN, CHAIN_RPC_URL } from '../lib/contracts';
+import { useFhevmDecrypt } from './useFhevmDecrypt';
+
+const client = createPublicClient({
+  chain: CHAIN,
+  transport: http(CHAIN_RPC_URL, { retryCount: 3, timeout: 10_000 }),
+});
+
+const ZERO_HANDLE = '0x' + '0'.repeat(64);
+
+export function useConfidentialBalance(confTokenAddress: `0x${string}`) {
+  const { address, isConnected } = useAccount();
+  const { decryptHandle, isDecrypting, isReady: fheReady } = useFhevmDecrypt();
+
+  const [handle, setHandle] = useState<string | null>(null);
+  const [decryptedBalance, setDecryptedBalance] = useState<bigint | null>(null);
+  const [isLoadingHandle, setIsLoadingHandle] = useState(false);
+
+  const fetchHandle = useCallback(async (): Promise<string | null> => {
+    if (!address) {
+      setHandle(null);
+      setDecryptedBalance(null);
+      return null;
+    }
+    setIsLoadingHandle(true);
+    try {
+      const result = await client.readContract({
+        address: confTokenAddress,
+        abi: CONF_TOKEN_ABI,
+        functionName: 'confidentialBalanceOf',
+        args: [address],
+      });
+      const h = result as string;
+      const newHandle = h && h !== ZERO_HANDLE ? h : null;
+      setHandle(newHandle);
+      setDecryptedBalance(null);
+      return newHandle;
+    } catch {
+      setHandle(null);
+      setDecryptedBalance(null);
+      return null;
+    } finally {
+      setIsLoadingHandle(false);
+    }
+  }, [address, confTokenAddress]);
+
+  useEffect(() => {
+    if (isConnected && address) void fetchHandle();
+    else {
+      setHandle(null);
+      setDecryptedBalance(null);
+    }
+  }, [isConnected, address, fetchHandle]);
+
+  const decrypt = useCallback(async () => {
+    if (!handle || !fheReady) return null;
+    const value = await decryptHandle(handle, confTokenAddress);
+    if (value !== null) setDecryptedBalance(value);
+    return value;
+  }, [handle, fheReady, decryptHandle, confTokenAddress]);
+
+  const refetchAndDecrypt = useCallback(async () => {
+    const newHandle = await fetchHandle();
+    if (newHandle && fheReady) {
+      const value = await decryptHandle(newHandle, confTokenAddress);
+      if (value !== null) setDecryptedBalance(value);
+    }
+  }, [fetchHandle, fheReady, decryptHandle, confTokenAddress]);
+
+  return {
+    handle,
+    hasBalance: !!handle,
+    decryptedBalance,
+    isDecrypted: decryptedBalance !== null,
+    isLoadingHandle,
+    isDecrypting,
+    fheReady,
+    decrypt,
+    refetch: fetchHandle,
+    refetchAndDecrypt,
+  };
+}

package/template/src/hooks/useConfidentialTransfer.ts

@@ -0,0 +1,50 @@
+/**
+ * Confidential transfer: encrypt amount and call confidentialTransfer(to, handle, inputProof).
+ * No relayer; SDK only.
+ */
+
+import { useCallback, useState } from 'react';
+import { useAccount, useWriteContract } from 'wagmi';
+import { CONF_TOKEN_ABI, TOKEN_CONFIGS, getConfTokenAddress, type TokenKey } from '../lib/contracts';
+import { parseAmount } from '../lib/utils';
+import { useFhevmEncrypt } from './useFhevmEncrypt';
+
+export function useConfidentialTransfer(tokenKey: TokenKey) {
+  const { address, isConnected } = useAccount();
+  const { encryptAmount, isReady: fheReady } = useFhevmEncrypt();
+  const { writeContractAsync, isPending } = useWriteContract();
+  const confToken = getConfTokenAddress(tokenKey);
+  const config = TOKEN_CONFIGS[tokenKey];
+
+  const [isTransferring, setIsTransferring] = useState(false);
+
+  const transfer = useCallback(
+    async (toAddress: `0x${string}`, amountHuman: string) => {
+      if (!address || !isConnected || !fheReady) return null;
+      const amount = parseAmount(amountHuman, config.decimals);
+      if (amount <= 0n) return null;
+      if (!toAddress || toAddress.length !== 42) return null;
+      setIsTransferring(true);
+      try {
+        const encrypted = await encryptAmount(amount, confToken);
+        if (!encrypted?.handles?.[0]) throw new Error('Encryption failed');
+        const hash = await writeContractAsync({
+          address: confToken,
+          abi: CONF_TOKEN_ABI,
+          functionName: 'confidentialTransfer',
+          args: [toAddress, encrypted.handles[0], encrypted.inputProof as `0x${string}`],
+        });
+        return hash;
+      } finally {
+        setIsTransferring(false);
+      }
+    },
+    [address, isConnected, fheReady, encryptAmount, writeContractAsync, confToken, config.decimals]
+  );
+
+  return {
+    transfer,
+    isTransferring: isTransferring || isPending,
+    fheReady,
+  };
+}

package/template/src/hooks/useFhevmDecrypt.ts

@@ -0,0 +1,67 @@
+/**
+ * FHEVM Decryption Hook - decrypt encrypted values using signature-based auth
+ */
+
+import { useCallback, useState } from 'react';
+import { useAccount, useSignTypedData } from 'wagmi';
+import { useFhevm } from '../providers/useFhevmContext';
+
+export function useFhevmDecrypt() {
+  const { instance, isReady, error } = useFhevm();
+  const { address, isConnected } = useAccount();
+  const { signTypedDataAsync } = useSignTypedData();
+  const [isDecrypting, setIsDecrypting] = useState(false);
+  const [decryptError, setDecryptError] = useState<Error | null>(null);
+
+  const decryptHandle = useCallback(
+    async (handle: string, contractAddress: string): Promise<bigint | null> => {
+      if (!instance || !address || !isReady || !isConnected) {
+        setDecryptError(new Error('FHEVM not ready or wallet not connected'));
+        return null;
+      }
+      if (!handle || handle === '0x' + '0'.repeat(64)) return 0n;
+      setIsDecrypting(true);
+      setDecryptError(null);
+      try {
+        const keypair = instance.generateKeypair();
+        const handleContractPairs = [{ handle, contractAddress }];
+        const startTimestamp = Math.floor(Date.now() / 1000).toString();
+        const durationDays = '10';
+        const contractAddresses = [contractAddress];
+        const eip712 = instance.createEIP712(
+          keypair.publicKey,
+          contractAddresses,
+          startTimestamp,
+          durationDays
+        );
+        const sigPayload = eip712 as { domain: unknown; types: Record<string, unknown>; message: unknown };
+        const signature = await signTypedDataAsync({
+          domain: sigPayload.domain as Record<string, unknown>,
+          types: (sigPayload.types || {}) as Record<string, unknown>,
+          message: sigPayload.message as Record<string, unknown>,
+          primaryType: 'UserDecryptRequestVerification',
+        });
+        const result = await instance.userDecrypt(
+          handleContractPairs,
+          keypair.privateKey,
+          keypair.publicKey,
+          signature.replace('0x', ''),
+          contractAddresses,
+          address,
+          startTimestamp,
+          durationDays
+        );
+        const value = result[handle];
+        return typeof value === 'bigint' ? value : BigInt(value ?? 0);
+      } catch (err) {
+        setDecryptError(err instanceof Error ? err : new Error('Decryption failed'));
+        return null;
+      } finally {
+        setIsDecrypting(false);
+      }
+    },
+    [instance, address, isReady, isConnected, signTypedDataAsync]
+  );
+
+  return { decryptHandle, isDecrypting, error: error || decryptError, isReady };
+}