create-shield-unshield-dapp 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +98 -8
  2. package/package.json +1 -1
  3. package/template/README.md +107 -17
  4. package/template/contracts/.env.example +8 -0
  5. package/template/contracts/README.md +74 -0
  6. package/template/contracts/contracts/ConfidentialTokenWrapper.sol +17 -0
  7. package/template/contracts/contracts/test/MockUSDC.sol +18 -0
  8. package/template/contracts/contracts/test/MockUSDT.sol +18 -0
  9. package/template/contracts/hardhat.config.ts +49 -0
  10. package/template/contracts/package.json +33 -0
  11. package/template/contracts/scripts/deploy-local.ts +62 -0
  12. package/template/contracts/scripts/deploy-sepolia.ts +52 -0
  13. package/template/contracts/tsconfig.json +15 -0
package/README.md CHANGED
@@ -1,6 +1,89 @@
1
1
  # create-shield-unshield-dapp
2
2
 
3
- 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.
3
+ Scaffold a **Shield/Unshield dApp** for the **Zama ecosystem**: let users wrap USDC/USDT into confidential tokens (cUSDC/cUSDT), send them privately, and unwrap back. Built on **ERC-7984** (confidential token standard). Ideal for projects that want to support shield/unshield and confidential transfers, and for developers new to Zama who want a working reference with clear documentation.
4
+
5
+ ## What you get
6
+
7
+ - A ready-to-run React + Vite app with wallet connection (e.g. Rainbow, MetaMask).
8
+ - **Wrap (shield):** USDC → cUSDC, USDT → cUSDT.
9
+ - **Unwrap (unshield):** Two-step flow (unwrap → finalizeUnwrap) with Zama relayer for decryption.
10
+ - **Confidential transfer:** Send cUSDC/cUSDT with amounts hidden on-chain.
11
+ - A **detailed README** in the scaffolded project (env vars, build, where to get Sepolia addresses).
12
+ - A **contracts/** folder with an ERC-7984 wrapper (same pattern as the payroll app), MockUSDC/MockUSDT, and Hardhat deploy scripts so you can **deploy your own tokens and wrappers** for local or Sepolia testing. See `contracts/README.md` after scaffolding.
13
+
14
+ ---
15
+
16
+ ## Token standard: ERC-7984
17
+
18
+ The scaffolded app uses **ERC-7984** (Confidential Token Standard). In short:
19
+
20
+ - **Underlying token:** A normal ERC-20 (e.g. USDC, USDT).
21
+ - **Confidential wrapper:** A contract that holds the underlying and mints/burns **confidential** balances. On-chain amounts are encrypted (FHE); only the owner and authorized systems can decrypt with a proof.
22
+ - **cUSDC / cUSDT:** The confidential versions of USDC and USDT. Balances are stored as encrypted handles; you see your balance by decrypting (e.g. via Zama’s relayer/gateway).
23
+
24
+ Key contract functions used in the app:
25
+
26
+ | Function | Purpose |
27
+ |----------|---------|
28
+ | `wrap(to, amount)` | Lock underlying (e.g. USDC) in the contract and mint confidential balance for `to`. |
29
+ | `unwrap(from, to, encryptedAmount, inputProof)` | Burn confidential balance and request unwrap; the amount is still encrypted until proven. Emits `UnwrapRequested`. |
30
+ | `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)` | Prove the burnt amount to the contract; contract releases that much underlying to the receiver. |
31
+ | `confidentialTransfer(to, encryptedAmount, inputProof)` | Transfer confidential balance to `to`; amount stays encrypted on-chain. |
32
+ | `confidentialBalanceOf(account)` | Returns an encrypted balance handle (decrypt off-chain to show amount). |
33
+
34
+ ---
35
+
36
+ ## How wrapping works (shield)
37
+
38
+ **Goal:** Turn public USDC/USDT into confidential cUSDC/cUSDT.
39
+
40
+ 1. **Approve:** User approves the confidential token contract to spend their underlying (USDC or USDT).
41
+ 2. **Wrap:** User calls `wrap(to, amount)` on the cUSDC/cUSDT contract. The contract:
42
+ - Pulls `amount` of underlying from the user (transferFrom).
43
+ - Mints confidential balance for `to` (the user). On-chain, the amount is stored in encrypted form.
44
+ 3. **Balance:** The user’s cUSDC/cUSDT balance increases (shown after decrypting the handle). Their USDC/USDT balance decreases.
45
+
46
+ No relayer needed for wrapping; it’s a single on-chain transaction.
47
+
48
+ ---
49
+
50
+ ## How unwrapping works (unshield) — two steps
51
+
52
+ **Goal:** Turn confidential cUSDC/cUSDT back into public USDC/USDT.
53
+
54
+ Unwrap is **two-step** because the contract only holds encrypted amounts. To release the right amount of underlying, the contract must be given a **decryption proof** that matches the burnt confidential amount. The Zama relayer (gateway) produces that proof after the first step.
55
+
56
+ ### Step 1: `unwrap(from, to, encryptedAmount, inputProof)`
57
+
58
+ 1. User chooses amount and the app **encrypts** it (FHE) for the contract, producing an encrypted handle and `inputProof`.
59
+ 2. User sends a tx calling `unwrap(from, to, encryptedAmount, inputProof)`. The contract:
60
+ - Burns the confidential balance corresponding to that encrypted amount.
61
+ - Emits `UnwrapRequested(receiver, amount)` where `amount` is the encrypted (handle) value.
62
+ - Does **not** send underlying yet — it waits for a decryption proof.
63
+ 3. The app (or backend) sends the emitted handle to the **Zama relayer**. The relayer decrypts it and returns a **decryption proof**.
64
+
65
+ ### Step 2: `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)`
66
+
67
+ 1. The app calls `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)` with:
68
+ - `burntAmount`: the handle from `UnwrapRequested`.
69
+ - `burntAmountCleartext`: the decrypted amount (so the contract can release the right amount).
70
+ - `decryptionProof`: proof from the relayer that the decryption is correct.
71
+ 2. The contract verifies the proof and sends `burntAmountCleartext` of underlying (USDC/USDT) to the receiver.
72
+ 3. User’s public USDC/USDT balance increases.
73
+
74
+ In the scaffolded app, both steps run in one flow after the user clicks Unwrap/Unshield: we wait for the unwrap tx, get the proof from the relayer, then call `finalizeUnwrap` and wait for that receipt so the UI can refetch balances and show the updated USDC/USDT.
75
+
76
+ ---
77
+
78
+ ## How confidential transfer works
79
+
80
+ **Goal:** Send cUSDC/cUSDT to another address without revealing the amount on-chain.
81
+
82
+ 1. Sender enters amount and recipient address.
83
+ 2. The app encrypts the amount (FHE) for the contract, producing an encrypted handle and `inputProof`.
84
+ 3. User sends a tx: `confidentialTransfer(to, encryptedAmount, inputProof)`. The contract deducts the encrypted amount from the sender and adds it to the recipient’s confidential balance. The amount stays encrypted; no relayer needed.
85
+
86
+ ---
4
87
 
5
88
  ## Install and run
6
89
 
@@ -8,23 +91,30 @@ Scaffold a **Shield/Unshield dApp** for wrapping and unwrapping USDC ↔ cUSDC a
8
91
  npx create-shield-unshield-dapp my-app
9
92
  cd my-app
10
93
  cp .env.example .env
11
- # Edit .env (see below)
94
+ # Edit .env (see below and scaffolded README)
95
+ npm install
12
96
  npm run dev
13
97
  ```
14
98
 
15
- Open the URL shown (e.g. http://localhost:5173) and connect your wallet.
99
+ Open the URL (e.g. http://localhost:5173) and connect your wallet to the correct network (Mainnet or Sepolia).
16
100
 
17
- ## Switching environment (mainnet vs testnet)
101
+ ---
18
102
 
19
- - **Mainnet:** In `.env` set `VITE_MAINNET=true`. Contract addresses are built-in. Optionally set `VITE_MAINNET_RPC_URL`. Connect your wallet to Ethereum Mainnet.
20
- - **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.
103
+ ## Mainnet vs testnet
21
104
 
22
- Full details, all environment variables, and where to get Sepolia addresses are in the **scaffolded project’s README** (`README.md` in the created folder).
105
+ - **Mainnet:** In `.env` set `VITE_MAINNET=true`. Contract addresses are built-in. Optionally set `VITE_MAINNET_RPC_URL`.
106
+ - **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`.
107
+
108
+ The **scaffolded project’s README** (`README.md` in the created folder) has full env docs, where to get Sepolia addresses, build, and preview.
109
+
110
+ ---
23
111
 
24
112
  ## Options
25
113
 
26
114
  - `npx create-shield-unshield-dapp my-app --force` — Overwrite existing files in `my-app` if it already exists.
27
- - `npx create-shield-unshield-dapp my-app --no-install` — Skip running `npm install` after copying (run it yourself).
115
+ - `npx create-shield-unshield-dapp my-app --no-install` — Skip `npm install` after copying (run it yourself).
116
+
117
+ ---
28
118
 
29
119
  ## License
30
120
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-shield-unshield-dapp",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
4
  "description": "Scaffold a Shield/Unshield dApp for USDC/cUSDC and USDT/cUSDT (wrap, unwrap, confidential transfer)",
5
5
  "type": "commonjs",
6
6
  "bin": {
package/template/README.md CHANGED
@@ -1,17 +1,95 @@
1
1
  # Shield / Unshield dApp
2
2
 
3
- 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.
3
+ A reference dApp for the **Zama ecosystem**: wrap and unwrap **USDC ↔ cUSDC** and **USDT ↔ cUSDT**, and **transfer** confidential tokens. Supports **Ethereum Mainnet** and **Sepolia** testnet. Built on **ERC-7984** (confidential token standard). Use it as a foundation or guide when implementing confidential tokens in your own project.
4
4
 
5
- ## Features
5
+ ---
6
6
 
7
- - **Wrap (shield):** USDC → cUSDC, USDT → cUSDT.
8
- - **Unwrap (unshield):** cUSDC → USDC, cUSDT → USDT (two-step flow via Zama gateway).
9
- - **Transfer:** Send cUSDC or cUSDT to any address; amount is encrypted on-chain.
7
+ ## Token standard: ERC-7984
8
+
9
+ This app uses **ERC-7984** (Confidential Token Standard). In short:
10
+
11
+ - **Underlying token:** A normal ERC-20 (e.g. USDC, USDT).
12
+ - **Confidential wrapper:** A contract that holds the underlying and mints/burns **confidential** balances. On-chain amounts are encrypted (FHE); only the owner and authorized systems can decrypt with a proof.
13
+ - **cUSDC / cUSDT:** The confidential versions of USDC and USDT. Balances are stored as encrypted handles; you see your balance by decrypting (e.g. via Zama’s relayer/gateway).
14
+
15
+ Key contract functions we use:
16
+
17
+ | Function | Purpose |
18
+ |----------|---------|
19
+ | `wrap(to, amount)` | Lock underlying (e.g. USDC) in the contract and mint confidential balance for `to`. |
20
+ | `unwrap(from, to, encryptedAmount, inputProof)` | Burn confidential balance and request unwrap; the amount is still encrypted until proven. Emits `UnwrapRequested`. |
21
+ | `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)` | Prove the burnt amount to the contract; contract releases that much underlying to the receiver. |
22
+ | `confidentialTransfer(to, encryptedAmount, inputProof)` | Transfer confidential balance to `to`; amount stays encrypted on-chain. |
23
+ | `confidentialBalanceOf(account)` | Returns an encrypted balance handle (decrypt off-chain to show amount). |
24
+
25
+ ---
26
+
27
+ ## How wrapping works (shield)
28
+
29
+ **Goal:** Turn public USDC/USDT into confidential cUSDC/cUSDT.
30
+
31
+ 1. **Approve:** User approves the confidential token contract to spend their underlying (USDC or USDT).
32
+ 2. **Wrap:** User calls `wrap(to, amount)` on the cUSDC/cUSDT contract. The contract:
33
+ - Pulls `amount` of underlying from the user (transferFrom).
34
+ - Mints confidential balance for `to` (the user). On-chain, the amount is stored in encrypted form.
35
+ 3. **Balance:** The user’s cUSDC/cUSDC balance increases (shown after decrypting the handle). Their USDC/USDT balance decreases.
36
+
37
+ No relayer needed for wrapping; it’s a single on-chain transaction.
38
+
39
+ ---
40
+
41
+ ## How unwrapping works (unshield) — two steps
42
+
43
+ **Goal:** Turn confidential cUSDC/cUSDT back into public USDC/USDT.
44
+
45
+ Unwrap is **two-step** because the contract only holds encrypted amounts. To release the right amount of underlying, the contract must be given a **decryption proof** that matches the burnt confidential amount. The Zama relayer (gateway) produces that proof after the first step.
46
+
47
+ ### Step 1: `unwrap(from, to, encryptedAmount, inputProof)`
48
+
49
+ 1. User chooses amount and the app **encrypts** it (FHE) for the contract, producing an encrypted handle and `inputProof`.
50
+ 2. User sends a tx calling `unwrap(from, to, encryptedAmount, inputProof)`. The contract:
51
+ - Burns the confidential balance corresponding to that encrypted amount.
52
+ - Emits `UnwrapRequested(receiver, amount)` where `amount` is the encrypted (handle) value.
53
+ - Does **not** send underlying yet — it waits for a decryption proof.
54
+ 3. The app (or backend) sends the emitted handle to the **Zama relayer**. The relayer decrypts it and returns a **decryption proof**.
55
+
56
+ ### Step 2: `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)`
57
+
58
+ 1. The app calls `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)` with:
59
+ - `burntAmount`: the handle from `UnwrapRequested`.
60
+ - `burntAmountCleartext`: the decrypted amount (so the contract can release the right amount).
61
+ - `decryptionProof`: proof from the relayer that the decryption is correct.
62
+ 2. The contract verifies the proof and sends `burntAmountCleartext` of underlying (USDC/USDT) to the receiver.
63
+ 3. User’s public USDC/USDT balance increases.
64
+
65
+ In this app, both steps run in one flow after the user clicks Unwrap/Unshield: we wait for the unwrap tx, get the proof from the relayer, then call `finalizeUnwrap` and wait for that receipt so the UI can refetch balances and show the updated USDC/USDT.
66
+
67
+ ---
68
+
69
+ ## How confidential transfer works
70
+
71
+ **Goal:** Send cUSDC/cUSDT to another address without revealing the amount on-chain.
72
+
73
+ 1. Sender enters amount and recipient address.
74
+ 2. The app encrypts the amount (FHE) for the contract, producing an encrypted handle and `inputProof`.
75
+ 3. User sends a tx: `confidentialTransfer(to, encryptedAmount, inputProof)`. The contract deducts the encrypted amount from the sender and adds it to the recipient’s confidential balance. The amount stays encrypted; no relayer needed.
76
+
77
+ ---
78
+
79
+ ## Features (summary)
80
+
81
+ - **Wrap (shield):** USDC → cUSDC, USDT → cUSDT (approve + one tx).
82
+ - **Unwrap (unshield):** cUSDC → USDC, cUSDT → USDT (two-step: unwrap tx → relayer proof → finalizeUnwrap tx).
83
+ - **Transfer:** Send cUSDC or cUSDT confidentially (one tx).
84
+
85
+ ---
10
86
 
11
87
  ## Prerequisites
12
88
 
13
89
  - Node.js 18+
14
- - A wallet (e.g. MetaMask) on the network you use (Mainnet or Sepolia).
90
+ - A wallet (e.g. MetaMask, Rainbow) on the network you use (Mainnet or Sepolia).
91
+
92
+ ---
15
93
 
16
94
  ## Quick start
17
95
 
@@ -21,7 +99,7 @@ A frontend for wrapping and unwrapping **USDC ↔ cUSDC** and **USDT ↔ cUSDT**
21
99
  npm install
22
100
  ```
23
101
 
24
- 2. Copy the example env file and edit it:
102
+ 2. Copy the example env and edit it:
25
103
 
26
104
  ```bash
27
105
  cp .env.example .env
@@ -39,17 +117,19 @@ A frontend for wrapping and unwrapping **USDC ↔ cUSDC** and **USDT ↔ cUSDT**
39
117
 
40
118
  5. Open the URL (e.g. http://localhost:5173), connect your wallet to the correct network (Sepolia or Mainnet), and use the app.
41
119
 
42
- ## Switching environment (mainnet vs testnet)
120
+ ---
43
121
 
44
- The app uses a single env flag to choose the network.
122
+ ## Mainnet vs testnet
45
123
 
46
- | Mode | Set in `.env` | Contract addresses |
47
- |----------|-----------------------------------|--------------------|
48
- | Testnet | `VITE_MAINNET=false` or omit | **Required:** `VITE_USDC_ADDRESS`, `VITE_CONF_USDC_ADDRESS`, `VITE_USDT_ADDRESS`, `VITE_CONF_USDT_ADDRESS` (Sepolia). |
49
- | Mainnet | `VITE_MAINNET=true` | **Built-in.** No address env vars needed. Optional: `VITE_MAINNET_RPC_URL`. |
124
+ | Mode | Set in `.env` | Contract addresses |
125
+ |---------|----------------------------------|--------------------|
126
+ | Testnet | `VITE_MAINNET=false` or omit | **Required:** `VITE_USDC_ADDRESS`, `VITE_CONF_USDC_ADDRESS`, `VITE_USDT_ADDRESS`, `VITE_CONF_USDT_ADDRESS` (Sepolia). |
127
+ | Mainnet | `VITE_MAINNET=true` | **Built-in.** Optional: `VITE_MAINNET_RPC_URL`. |
50
128
 
51
- - **After changing** `.env`, restart the dev server (`npm run dev`) or rebuild for production (`npm run build`).
52
- - **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).
129
+ - After changing `.env`, restart the dev server (`npm run dev`) or rebuild (`npm run build`).
130
+ - 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).
131
+
132
+ ---
53
133
 
54
134
  ## Environment variables
55
135
 
@@ -64,9 +144,15 @@ The app uses a single env flag to choose the network.
64
144
  | `VITE_MAINNET_RPC_URL` | No | Mainnet RPC URL when `VITE_MAINNET=true` (default: public RPC). |
65
145
  | `VITE_WALLETCONNECT_PROJECT_ID` | No | WalletConnect project ID (optional). |
66
146
 
147
+ ---
148
+
67
149
  ## Where to get Sepolia addresses
68
150
 
69
- 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.
151
+ Obtain the USDC, cUSDC, USDT, and cUSDT contract addresses from your deployment or from Zama/contract documentation. The app does not ship valid default addresses for Sepolia.
152
+
153
+ **Testing with your own contracts:** If you have the `contracts/` folder (ERC-7984 wrapper + mocks + Hardhat), you can deploy your own wrappers and mocks for local or Sepolia testing. Run `npm run deploy:local` or `npm run deploy:sepolia` in the `contracts/` directory and paste the printed addresses into this app’s `.env`. See `contracts/README.md` in the same project.
154
+
155
+ ---
70
156
 
71
157
  ## Build and preview
72
158
 
@@ -74,18 +160,22 @@ Obtain the USDC, cUSDC, USDT, and cUSDT contract addresses from your deployment
74
160
  npm run build
75
161
  ```
76
162
 
77
- Output is in `dist/`. To serve it locally:
163
+ Output is in `dist/`. To serve locally:
78
164
 
79
165
  ```bash
80
166
  npm run preview
81
167
  ```
82
168
 
169
+ ---
170
+
83
171
  ## Architecture
84
172
 
85
173
  - **Frontend only:** No backend or indexer; reads from the chain and uses the Zama relayer for unwrap decryption proof.
86
174
  - **Contracts:** ERC-7984 confidential token wrappers with `wrap`, `unwrap`, `finalizeUnwrap`, and `confidentialTransfer`.
87
175
  - **Two token pairs:** USDC/cUSDC and USDT/cUSDT; on testnet you supply all four addresses via env; on mainnet they are built-in.
88
176
 
177
+ ---
178
+
89
179
  ## License
90
180
 
91
181
  MIT.
package/template/contracts/.env.example ADDED
@@ -0,0 +1,8 @@
1
+ # Funded Sepolia wallet (for deploy-sepolia only)
2
+ PRIVATE_KEY=0x...
3
+
4
+ # Optional: RPC URL for Sepolia (default: https://rpc.sepolia.org)
5
+ # SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
6
+
7
+ # Optional: only for deploy-sepolia if you have a USDT contract on Sepolia
8
+ # USDT_SEPOLIA=0x...
package/template/contracts/README.md ADDED
@@ -0,0 +1,74 @@
1
+ # Shield / Unshield — contracts
2
+
3
+ ERC-7984 confidential token **wrapper** and **mock tokens** for local and Sepolia testing. New to Zama? Deploy these to get your own cUSDC/cUSDT and point the frontend at them.
4
+
5
+ ## What’s here
6
+
7
+ - **ConfidentialTokenWrapper.sol** — Wraps any ERC-20 (e.g. USDC, USDT) into an ERC-7984 confidential token (wrap, unwrap, finalizeUnwrap, confidentialTransfer). Same pattern as the payroll app’s `ConfidentialPayrollToken`.
8
+ - **MockUSDC.sol / MockUSDT.sol** — Simple ERC-20 mocks (6 decimals, `mint`) for **local testing only**. Do not use on mainnet.
9
+ - **deploy-local.ts** — Deploys mocks + two wrappers on Hardhat network, mints test tokens to deployer, prints addresses for frontend `.env`.
10
+ - **deploy-sepolia.ts** — Deploys wrappers on Sepolia using real USDC (and optional USDT). You need a funded Sepolia wallet.
11
+
12
+ ## Prerequisites
13
+
14
+ - Node.js 20+
15
+ - For Sepolia: a funded Sepolia account (set `PRIVATE_KEY` in `.env`).
16
+
17
+ ## Setup
18
+
19
+ ```bash
20
+ cd contracts
21
+ npm install --legacy-peer-deps
22
+ cp .env.example .env
23
+ # Edit .env: set PRIVATE_KEY for Sepolia deploys
24
+ ```
25
+
26
+ (Use `--legacy-peer-deps` because of a peer dependency between `@openzeppelin/confidential-contracts` and `@fhevm/solidity`.)
27
+
28
+ ## Compile
29
+
30
+ ```bash
31
+ npm run compile
32
+ ```
33
+
34
+ ## Deploy for local testing (Hardhat network)
35
+
36
+ Deploys MockUSDC, MockUSDT, and two ConfidentialTokenWrappers (cUSDC, cUSDT), then mints 1M of each mock to the deployer.
37
+
38
+ ```bash
39
+ npm run deploy:local
40
+ ```
41
+
42
+ Copy the printed addresses into the **frontend** `.env` (see script output). To use the frontend against this local chain, you must run a local node (e.g. `npx hardhat node`) in another terminal and point the frontend at it; the app’s testnet mode expects Sepolia by default, so you may need to add the Hardhat network (chainId 31337) to your wallet and use the same mnemonic.
43
+
44
+ ## Deploy to Sepolia
45
+
46
+ Uses **real USDC** on Sepolia. Optionally set `USDT_SEPOLIA` in `.env` if you have a USDT contract on Sepolia; otherwise only cUSDC is deployed.
47
+
48
+ ```bash
49
+ npm run deploy:sepolia
50
+ ```
51
+
52
+ Copy the printed addresses into the **frontend** `.env`:
53
+
54
+ - `VITE_MAINNET=false`
55
+ - `VITE_USDC_ADDRESS=...`
56
+ - `VITE_CONF_USDC_ADDRESS=...`
57
+ - `VITE_USDT_ADDRESS=...` (or leave zero if you didn’t deploy cUSDT)
58
+ - `VITE_CONF_USDT_ADDRESS=...`
59
+
60
+ Then run the frontend (`npm run dev` in the frontend folder), connect your wallet to Sepolia, and use the dApp.
61
+
62
+ ## Contract overview (ERC-7984)
63
+
64
+ - **ConfidentialTokenWrapper** extends OpenZeppelin’s `ERC7984ERC20Wrapper` and Zama’s `ZamaEthereumConfig`. It:
65
+ - **wrap(to, amount)** — Pulls underlying from caller, mints confidential balance to `to`.
66
+ - **unwrap(from, to, encryptedAmount, inputProof)** — Burns confidential balance, emits `UnwrapRequested`; relayer produces decryption proof.
67
+ - **finalizeUnwrap(burntAmount, cleartext, decryptionProof)** — Verifies proof and sends underlying to receiver.
68
+ - **confidentialTransfer(to, encryptedAmount, inputProof)** — Transfers confidential balance; amount stays encrypted.
69
+
70
+ The frontend README has a longer explanation of the token standard and the wrap/unwrap/finalize flow.
71
+
72
+ ## License
73
+
74
+ MIT (contracts); BSD-3-Clause for code that follows the Zama/OpenZeppelin confidential-contracts pattern.
package/template/contracts/contracts/ConfidentialTokenWrapper.sol ADDED
@@ -0,0 +1,17 @@
1
+ // SPDX-License-Identifier: BSD-3-Clause
2
+ pragma solidity ^0.8.27;
3
+
4
+ import "@openzeppelin/confidential-contracts/token/ERC7984/extensions/ERC7984ERC20Wrapper.sol";
5
+ import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
6
+
7
+ /// @title ConfidentialTokenWrapper
8
+ /// @notice ERC-7984 wrapper: wraps a public ERC20 (e.g. USDC, USDT) into a confidential token
9
+ /// for shield/unshield and confidential transfers.
10
+ contract ConfidentialTokenWrapper is ZamaEthereumConfig, ERC7984ERC20Wrapper {
11
+ constructor(
12
+ address underlyingToken,
13
+ string memory name,
14
+ string memory symbol,
15
+ string memory uri
16
+ ) ERC7984(name, symbol, uri) ERC7984ERC20Wrapper(IERC20(underlyingToken)) {}
17
+ }
package/template/contracts/contracts/test/MockUSDC.sol ADDED
@@ -0,0 +1,18 @@
1
+ // SPDX-License-Identifier: MIT
2
+ pragma solidity ^0.8.27;
3
+
4
+ import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
5
+
6
+ /// @title MockUSDC — Test-only mock for USDC
7
+ /// @notice Simple ERC20 with 6 decimals for local/testing. DO NOT use on mainnet.
8
+ contract MockUSDC is ERC20 {
9
+ constructor() ERC20("USD Coin", "USDC") {}
10
+
11
+ function decimals() public pure override returns (uint8) {
12
+ return 6;
13
+ }
14
+
15
+ function mint(address to, uint256 amount) external {
16
+ _mint(to, amount);
17
+ }
18
+ }
package/template/contracts/contracts/test/MockUSDT.sol ADDED
@@ -0,0 +1,18 @@
1
+ // SPDX-License-Identifier: MIT
2
+ pragma solidity ^0.8.27;
3
+
4
+ import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
5
+
6
+ /// @title MockUSDT — Test-only mock for USDT
7
+ /// @notice Simple ERC20 with 6 decimals for local/testing. DO NOT use on mainnet.
8
+ contract MockUSDT is ERC20 {
9
+ constructor() ERC20("Tether USD", "USDT") {}
10
+
11
+ function decimals() public pure override returns (uint8) {
12
+ return 6;
13
+ }
14
+
15
+ function mint(address to, uint256 amount) external {
16
+ _mint(to, amount);
17
+ }
18
+ }
package/template/contracts/hardhat.config.ts ADDED
@@ -0,0 +1,49 @@
1
+ import "@fhevm/hardhat-plugin";
2
+ import "@nomicfoundation/hardhat-ethers";
3
+ import "@typechain/hardhat";
4
+ import type { HardhatUserConfig } from "hardhat/config";
5
+ import "dotenv/config";
6
+
7
+ const MNEMONIC =
8
+ process.env.MNEMONIC ??
9
+ "test test test test test test test test test test test junk";
10
+
11
+ const SEPOLIA_RPC_URL =
12
+ process.env.SEPOLIA_RPC_URL ?? "https://rpc.sepolia.org";
13
+ const PRIVATE_KEY = process.env.PRIVATE_KEY ?? "";
14
+
15
+ const config: HardhatUserConfig = {
16
+ defaultNetwork: "hardhat",
17
+ networks: {
18
+ hardhat: {
19
+ accounts: { mnemonic: MNEMONIC },
20
+ chainId: 31337,
21
+ },
22
+ sepolia: {
23
+ accounts: PRIVATE_KEY ? [PRIVATE_KEY] : { mnemonic: MNEMONIC, count: 10 },
24
+ chainId: 11155111,
25
+ url: SEPOLIA_RPC_URL,
26
+ },
27
+ },
28
+ paths: {
29
+ artifacts: "./artifacts",
30
+ cache: "./cache",
31
+ sources: "./contracts",
32
+ tests: "./test",
33
+ },
34
+ solidity: {
35
+ version: "0.8.27",
36
+ settings: {
37
+ metadata: { bytecodeHash: "none" },
38
+ optimizer: { enabled: true, runs: 800 },
39
+ viaIR: true,
40
+ evmVersion: "cancun",
41
+ },
42
+ },
43
+ typechain: {
44
+ outDir: "types",
45
+ target: "ethers-v6",
46
+ },
47
+ };
48
+
49
+ export default config;
package/template/contracts/package.json ADDED
@@ -0,0 +1,33 @@
1
+ {
2
+ "name": "shield-unshield-contracts",
3
+ "version": "1.0.0",
4
+ "description": "ERC-7984 wrapper and mocks for Shield/Unshield dApp (local and Sepolia)",
5
+ "private": true,
6
+ "scripts": {
7
+ "compile": "hardhat compile",
8
+ "deploy:local": "hardhat run scripts/deploy-local.ts --network hardhat",
9
+ "deploy:sepolia": "hardhat run scripts/deploy-sepolia.ts --network sepolia"
10
+ },
11
+ "devDependencies": {
12
+ "@fhevm/hardhat-plugin": "^0.3.0-4",
13
+ "@fhevm/mock-utils": "0.3.0-4",
14
+ "@nomicfoundation/hardhat-ethers": "^3.1.0",
15
+ "@zama-fhe/relayer-sdk": "^0.3.0-8",
16
+ "@typechain/ethers-v6": "^0.5.1",
17
+ "@typechain/hardhat": "^9.1.0",
18
+ "dotenv": "^16.3.1",
19
+ "typechain": "^8.3.2",
20
+ "ethers": "^6.15.0",
21
+ "hardhat": "^2.26.0",
22
+ "ts-node": "^10.9.2",
23
+ "typescript": "^5.3.3"
24
+ },
25
+ "dependencies": {
26
+ "@fhevm/solidity": "^0.10.0",
27
+ "@openzeppelin/confidential-contracts": "^0.3.0",
28
+ "@openzeppelin/contracts": "^5.0.2"
29
+ },
30
+ "engines": {
31
+ "node": ">=20"
32
+ }
33
+ }
package/template/contracts/scripts/deploy-local.ts ADDED
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Deploy mock tokens + ERC-7984 wrappers on local Hardhat network for testing.
3
+ * Usage: npx hardhat run scripts/deploy-local.ts --network hardhat
4
+ *
5
+ * Then run the frontend with these addresses in .env (VITE_MAINNET=false and the four addresses).
6
+ * Note: Hardhat local chainId is 31337; the frontend expects Sepolia (11155111) by default for
7
+ * testnet. For local testing you may need to add Hardhat network to your wallet and use the
8
+ * same mnemonic, or run the frontend against Sepolia and use deploy-sepolia.ts instead.
9
+ */
10
+ import { ethers } from "hardhat";
11
+
12
+ const MINT_AMOUNT = ethers.parseUnits("1000000", 6); // 1M units (6 decimals)
13
+
14
+ async function main() {
15
+ const [deployer] = await ethers.getSigners();
16
+ console.log("Deploying with account:", deployer.address);
17
+
18
+ // 1. Deploy mocks
19
+ const MockUSDC = await ethers.getContractFactory("MockUSDC");
20
+ const mockUsdc = await MockUSDC.deploy();
21
+ await mockUsdc.waitForDeployment();
22
+ const usdcAddr = await mockUsdc.getAddress();
23
+ console.log("MockUSDC deployed to:", usdcAddr);
24
+
25
+ const MockUSDT = await ethers.getContractFactory("MockUSDT");
26
+ const mockUsdt = await MockUSDT.deploy();
27
+ await mockUsdt.waitForDeployment();
28
+ const usdtAddr = await mockUsdt.getAddress();
29
+ console.log("MockUSDT deployed to:", usdtAddr);
30
+
31
+ // 2. Deploy wrappers (ERC-7984)
32
+ const Wrapper = await ethers.getContractFactory("ConfidentialTokenWrapper");
33
+
34
+ const cUsdc = await Wrapper.deploy(usdcAddr, "Confidential USDC", "cUSDC", "");
35
+ await cUsdc.waitForDeployment();
36
+ const cUsdcAddr = await cUsdc.getAddress();
37
+ console.log("ConfidentialTokenWrapper (cUSDC) deployed to:", cUsdcAddr);
38
+
39
+ const cUsdt = await Wrapper.deploy(usdtAddr, "Confidential USDT", "cUSDT", "");
40
+ await cUsdt.waitForDeployment();
41
+ const cUsdtAddr = await cUsdt.getAddress();
42
+ console.log("ConfidentialTokenWrapper (cUSDT) deployed to:", cUsdtAddr);
43
+
44
+ // 3. Mint test tokens to deployer
45
+ await mockUsdc.mint(deployer.address, MINT_AMOUNT);
46
+ await mockUsdt.mint(deployer.address, MINT_AMOUNT);
47
+ console.log("Minted 1_000_000 USDC and USDT to", deployer.address);
48
+
49
+ console.log("\n=== Add to frontend .env (testnet / local) ===");
50
+ console.log(`VITE_MAINNET=false`);
51
+ console.log(`VITE_USDC_ADDRESS=${usdcAddr}`);
52
+ console.log(`VITE_CONF_USDC_ADDRESS=${cUsdcAddr}`);
53
+ console.log(`VITE_USDT_ADDRESS=${usdtAddr}`);
54
+ console.log(`VITE_CONF_USDT_ADDRESS=${cUsdtAddr}`);
55
+ }
56
+
57
+ main()
58
+ .then(() => process.exit(0))
59
+ .catch((err) => {
60
+ console.error(err);
61
+ process.exit(1);
62
+ });
package/template/contracts/scripts/deploy-sepolia.ts ADDED
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Deploy ERC-7984 wrappers on Sepolia using real USDC (and optional USDT).
3
+ * Usage: npx hardhat run scripts/deploy-sepolia.ts --network sepolia
4
+ *
5
+ * Requires PRIVATE_KEY in .env (funded Sepolia wallet).
6
+ * Uses real USDC on Sepolia. If you don't have Sepolia USDT, set VITE_USDT_ADDRESS and
7
+ * VITE_CONF_USDT_ADDRESS to zero or omit USDT in the app.
8
+ */
9
+ import { ethers } from "hardhat";
10
+
11
+ // Real USDC on Sepolia (Circle)
12
+ const USDC_SEPOLIA = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238";
13
+ // Sepolia often has a USDT-equivalent or test token; set if you have one, or deploy MockUSDT first
14
+ const USDT_SEPOLIA = process.env.USDT_SEPOLIA ?? "0x0000000000000000000000000000000000000000";
15
+
16
+ async function main() {
17
+ const [deployer] = await ethers.getSigners();
18
+ console.log("Deploying with account:", deployer.address);
19
+ console.log("Account balance:", (await ethers.provider.getBalance(deployer.address)).toString());
20
+
21
+ const Wrapper = await ethers.getContractFactory("ConfidentialTokenWrapper");
22
+
23
+ // cUSDC
24
+ const cUsdc = await Wrapper.deploy(USDC_SEPOLIA, "Confidential USDC", "cUSDC", "");
25
+ await cUsdc.waitForDeployment();
26
+ const cUsdcAddr = await cUsdc.getAddress();
27
+ console.log("ConfidentialTokenWrapper (cUSDC) deployed to:", cUsdcAddr);
28
+
29
+ let cUsdtAddr = "0x0000000000000000000000000000000000000000";
30
+ if (USDT_SEPOLIA !== "0x0000000000000000000000000000000000000000") {
31
+ const cUsdt = await Wrapper.deploy(USDT_SEPOLIA, "Confidential USDT", "cUSDT", "");
32
+ await cUsdt.waitForDeployment();
33
+ cUsdtAddr = await cUsdt.getAddress();
34
+ console.log("ConfidentialTokenWrapper (cUSDT) deployed to:", cUsdtAddr);
35
+ } else {
36
+ console.log("Skipping cUSDT (no USDT_SEPOLIA in .env).");
37
+ }
38
+
39
+ console.log("\n=== Add to frontend .env (Sepolia) ===");
40
+ console.log(`VITE_MAINNET=false`);
41
+ console.log(`VITE_USDC_ADDRESS=${USDC_SEPOLIA}`);
42
+ console.log(`VITE_CONF_USDC_ADDRESS=${cUsdcAddr}`);
43
+ console.log(`VITE_USDT_ADDRESS=${USDT_SEPOLIA}`);
44
+ console.log(`VITE_CONF_USDT_ADDRESS=${cUsdtAddr}`);
45
+ }
46
+
47
+ main()
48
+ .then(() => process.exit(0))
49
+ .catch((err) => {
50
+ console.error(err);
51
+ process.exit(1);
52
+ });
package/template/contracts/tsconfig.json ADDED
@@ -0,0 +1,15 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "es2022",
4
+ "module": "commonjs",
5
+ "moduleResolution": "node",
6
+ "strict": true,
7
+ "esModuleInterop": true,
8
+ "skipLibCheck": true,
9
+ "forceConsistentCasingInFileNames": true,
10
+ "resolveJsonModule": true,
11
+ "outDir": "dist"
12
+ },
13
+ "include": ["scripts/**/*", "hardhat.config.ts"],
14
+ "exclude": ["node_modules"]
15
+ }