create-shield-unshield-dapp 1.0.1 → 1.0.2

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 (3) hide show
  1. package/README.md +97 -8
  2. package/package.json +1 -1
  3. package/template/README.md +105 -17
package/README.md CHANGED
@@ -1,6 +1,88 @@
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
+
13
+ ---
14
+
15
+ ## Token standard: ERC-7984
16
+
17
+ The scaffolded app uses **ERC-7984** (Confidential Token Standard). In short:
18
+
19
+ - **Underlying token:** A normal ERC-20 (e.g. USDC, USDT).
20
+ - **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.
21
+ - **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).
22
+
23
+ Key contract functions used in the app:
24
+
25
+ | Function | Purpose |
26
+ |----------|---------|
27
+ | `wrap(to, amount)` | Lock underlying (e.g. USDC) in the contract and mint confidential balance for `to`. |
28
+ | `unwrap(from, to, encryptedAmount, inputProof)` | Burn confidential balance and request unwrap; the amount is still encrypted until proven. Emits `UnwrapRequested`. |
29
+ | `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)` | Prove the burnt amount to the contract; contract releases that much underlying to the receiver. |
30
+ | `confidentialTransfer(to, encryptedAmount, inputProof)` | Transfer confidential balance to `to`; amount stays encrypted on-chain. |
31
+ | `confidentialBalanceOf(account)` | Returns an encrypted balance handle (decrypt off-chain to show amount). |
32
+
33
+ ---
34
+
35
+ ## How wrapping works (shield)
36
+
37
+ **Goal:** Turn public USDC/USDT into confidential cUSDC/cUSDT.
38
+
39
+ 1. **Approve:** User approves the confidential token contract to spend their underlying (USDC or USDT).
40
+ 2. **Wrap:** User calls `wrap(to, amount)` on the cUSDC/cUSDT contract. The contract:
41
+ - Pulls `amount` of underlying from the user (transferFrom).
42
+ - Mints confidential balance for `to` (the user). On-chain, the amount is stored in encrypted form.
43
+ 3. **Balance:** The user’s cUSDC/cUSDT balance increases (shown after decrypting the handle). Their USDC/USDT balance decreases.
44
+
45
+ No relayer needed for wrapping; it’s a single on-chain transaction.
46
+
47
+ ---
48
+
49
+ ## How unwrapping works (unshield) — two steps
50
+
51
+ **Goal:** Turn confidential cUSDC/cUSDT back into public USDC/USDT.
52
+
53
+ 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.
54
+
55
+ ### Step 1: `unwrap(from, to, encryptedAmount, inputProof)`
56
+
57
+ 1. User chooses amount and the app **encrypts** it (FHE) for the contract, producing an encrypted handle and `inputProof`.
58
+ 2. User sends a tx calling `unwrap(from, to, encryptedAmount, inputProof)`. The contract:
59
+ - Burns the confidential balance corresponding to that encrypted amount.
60
+ - Emits `UnwrapRequested(receiver, amount)` where `amount` is the encrypted (handle) value.
61
+ - Does **not** send underlying yet — it waits for a decryption proof.
62
+ 3. The app (or backend) sends the emitted handle to the **Zama relayer**. The relayer decrypts it and returns a **decryption proof**.
63
+
64
+ ### Step 2: `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)`
65
+
66
+ 1. The app calls `finalizeUnwrap(burntAmount, burntAmountCleartext, decryptionProof)` with:
67
+ - `burntAmount`: the handle from `UnwrapRequested`.
68
+ - `burntAmountCleartext`: the decrypted amount (so the contract can release the right amount).
69
+ - `decryptionProof`: proof from the relayer that the decryption is correct.
70
+ 2. The contract verifies the proof and sends `burntAmountCleartext` of underlying (USDC/USDT) to the receiver.
71
+ 3. User’s public USDC/USDT balance increases.
72
+
73
+ 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.
74
+
75
+ ---
76
+
77
+ ## How confidential transfer works
78
+
79
+ **Goal:** Send cUSDC/cUSDT to another address without revealing the amount on-chain.
80
+
81
+ 1. Sender enters amount and recipient address.
82
+ 2. The app encrypts the amount (FHE) for the contract, producing an encrypted handle and `inputProof`.
83
+ 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.
84
+
85
+ ---
4
86
 
5
87
  ## Install and run
6
88
 
@@ -8,23 +90,30 @@ Scaffold a **Shield/Unshield dApp** for wrapping and unwrapping USDC ↔ cUSDC a
8
90
  npx create-shield-unshield-dapp my-app
9
91
  cd my-app
10
92
  cp .env.example .env
11
- # Edit .env (see below)
93
+ # Edit .env (see below and scaffolded README)
94
+ npm install
12
95
  npm run dev
13
96
  ```
14
97
 
15
- Open the URL shown (e.g. http://localhost:5173) and connect your wallet.
98
+ Open the URL (e.g. http://localhost:5173) and connect your wallet to the correct network (Mainnet or Sepolia).
16
99
 
17
- ## Switching environment (mainnet vs testnet)
100
+ ---
18
101
 
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.
102
+ ## Mainnet vs testnet
21
103
 
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).
104
+ - **Mainnet:** In `.env` set `VITE_MAINNET=true`. Contract addresses are built-in. Optionally set `VITE_MAINNET_RPC_URL`.
105
+ - **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`.
106
+
107
+ The **scaffolded project’s README** (`README.md` in the created folder) has full env docs, where to get Sepolia addresses, build, and preview.
108
+
109
+ ---
23
110
 
24
111
  ## Options
25
112
 
26
113
  - `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).
114
+ - `npx create-shield-unshield-dapp my-app --no-install` — Skip `npm install` after copying (run it yourself).
115
+
116
+ ---
28
117
 
29
118
  ## License
30
119
 
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.2",
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
+ ---
121
+
122
+ ## Mainnet vs testnet
43
123
 
44
- The app uses a single env flag to choose the network.
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`. |
45
128
 
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`. |
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).
50
131
 
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).
132
+ ---
53
133
 
54
134
  ## Environment variables
55
135
 
@@ -64,9 +144,13 @@ 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
+ ---
70
154
 
71
155
  ## Build and preview
72
156
 
@@ -74,18 +158,22 @@ Obtain the USDC, cUSDC, USDT, and cUSDT contract addresses from your deployment
74
158
  npm run build
75
159
  ```
76
160
 
77
- Output is in `dist/`. To serve it locally:
161
+ Output is in `dist/`. To serve locally:
78
162
 
79
163
  ```bash
80
164
  npm run preview
81
165
  ```
82
166
 
167
+ ---
168
+
83
169
  ## Architecture
84
170
 
85
171
  - **Frontend only:** No backend or indexer; reads from the chain and uses the Zama relayer for unwrap decryption proof.
86
172
  - **Contracts:** ERC-7984 confidential token wrappers with `wrap`, `unwrap`, `finalizeUnwrap`, and `confidentialTransfer`.
87
173
  - **Two token pairs:** USDC/cUSDC and USDT/cUSDT; on testnet you supply all four addresses via env; on mainnet they are built-in.
88
174
 
175
+ ---
176
+
89
177
  ## License
90
178
 
91
179
  MIT.