Skip to content

Commit 2241b23

Browse files
alejoamirasalejoamiras
committed
docs: add comprehensive readme for noir-hardhat template
1 parent 76ee8ad commit 2241b23

File tree

1 file changed

+219
-9
lines changed

1 file changed

+219
-9
lines changed

‎README.md‎

Lines changed: 219 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,223 @@
1-
# Sample Hardhat Project
1+
# Noir + Hardhat Template 🚀
22

3-
This project demonstrates a basic Hardhat use case. It comes with a sample contract, a test for that contract, and a Hardhat Ignition module that deploys that contract.
3+
A comprehensive boilerplate that seamlessly integrates [Noir](https://noir-lang.org/) zero-knowledge circuits with [Hardhat](https://hardhat.org/) for Ethereum smart contract development. This template provides everything you need to build, test, and deploy ZK applications with enterprise-grade CI/CD pipelines.
44

5-
Try running some of the following tasks:
5+
## ✨ Features
66

7-
```shell
8-
npx hardhat help
9-
npx hardhat test
10-
REPORT_GAS=true npx hardhat test
11-
npx hardhat node
12-
npx hardhat ignition deploy ./ignition/modules/Lock.ts
7+
- **🔒 Zero-Knowledge Circuit Development** - Write and test Noir circuits with full TypeScript integration
8+
- **⚡ Hardhat Integration** - Leverage Hardhat's powerful development environment for smart contracts
9+
- **🧪 Comprehensive Testing** - TypeScript tests for both circuits and smart contracts with dynamic proof generation
10+
- **🚀 CI/CD Pipeline** - Automated testing, building, and validation with GitHub Actions
11+
- **📦 Multiple Proof Formats** - Handle proofs in JSON, binary, and Solidity-compatible formats
12+
- **🌐 Deployment Ready** - Hardhat Ignition integration for seamless Sepolia deployment
13+
- **📋 Code Quality** - Commitlint + Husky for conventional commits and code standards
14+
- **🔧 Development Tools** - Hot reloading, error handling, and debugging support
15+
16+
## 🏗️ What You'll Learn
17+
18+
This template demonstrates a complete **SimpleCounter** example that showcases:
19+
20+
- **Circuit Development**: Create a Noir circuit that verifies arithmetic operations
21+
- **Proof Generation**: Generate zero-knowledge proofs using the `bb` proving system
22+
- **Smart Contract Verification**: Verify proofs on-chain using auto-generated Solidity verifiers
23+
- **Full-Stack Integration**: TypeScript tests that create, verify, and submit proofs dynamically
24+
- **Production Deployment**: Deploy and interact with your ZK application on Ethereum testnets
25+
26+
## 📋 Prerequisites
27+
28+
Before getting started, ensure you have:
29+
30+
- **Node.js** (v18 or later) and **Yarn**
31+
- **Noir toolchain** - Install via [noirup](https://noir-lang.org/docs/getting_started/quick_start#installation)
32+
- **Barretenberg** (`bb`) - Usually installed with Noir, or install separately
33+
- **Git** for version control
34+
35+
```bash
36+
# Install Noir toolchain
37+
curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash
38+
noirup
39+
40+
# Verify installations
41+
nargo --version
42+
bb --version
43+
```
44+
45+
## 🚀 Quick Start
46+
47+
1. **Clone and Install**
48+
```bash
49+
git clone <repository-url>
50+
cd noir-hardhat-template
51+
yarn install
52+
```
53+
54+
2. **Build the Circuit**
55+
```bash
56+
yarn circuit:build
57+
```
58+
59+
3. **Test Everything**
60+
```bash
61+
# Test the Noir circuit
62+
yarn circuit:test
63+
64+
# Test smart contracts with proof verification
65+
yarn contracts:test
66+
```
67+
68+
4. **Generate and Verify Proofs**
69+
```bash
70+
# Generate witness and verification key
71+
yarn circuit:witness
72+
yarn circuit:vk
73+
74+
# Create and verify a proof
75+
yarn circuit:prove
76+
yarn circuit:verify
77+
```
78+
79+
## 📁 Project Structure
80+
81+
```
82+
noir-hardhat-template/
83+
├── circuit/ # Noir circuit source code
84+
│ ├── src/main.nr # Main circuit logic (SimpleCounter)
85+
│ ├── Nargo.toml # Circuit configuration
86+
│ ├── Prover.toml # Proving parameters
87+
│ └── target/ # Compiled circuit artifacts
88+
├── contracts/ # Solidity smart contracts
89+
│ ├── SimpleCounter.sol # Main contract with ZK verification
90+
│ └── VerifierKeccak.sol # Auto-generated proof verifier
91+
├── test/ # TypeScript test suites
92+
│ └── SimpleCounter.ts # Comprehensive integration tests
93+
├── ignition/ # Hardhat Ignition deployment modules
94+
│ └── modules/
95+
│ └── SimpleCounter.ts # Deployment configuration
96+
├── .github/workflows/ # CI/CD pipeline configuration
97+
└── hardhat.config.ts # Hardhat configuration
98+
```
99+
100+
## 🛠️ Available Scripts
101+
102+
### Circuit Operations
103+
```bash
104+
yarn circuit:build # Compile Noir circuit
105+
yarn circuit:test # Run circuit tests
106+
yarn circuit:witness # Generate witness from inputs
107+
yarn circuit:vk # Generate verification key
108+
yarn circuit:prove # Generate zero-knowledge proof
109+
yarn circuit:verify # Verify generated proof
110+
yarn circuit:solidity_verifier # Generate Solidity verifier contract
111+
```
112+
113+
### Smart Contract Operations
114+
```bash
115+
yarn contracts:compile # Compile Solidity contracts
116+
yarn contracts:test # Run smart contract tests
117+
yarn contracts:deploy # Deploy to Sepolia testnet
118+
```
119+
120+
### Development Tools
121+
```bash
122+
yarn commitlint # Validate commit messages
123+
yarn commitlint:last # Check last commit message
124+
```
125+
126+
## 🔄 CI/CD Pipeline
127+
128+
Our GitHub Actions pipeline ensures code quality and functionality across all components:
129+
130+
### **Automated Workflows**
131+
132+
- **🔍 Commit Validation** - Enforces conventional commit standards on all PRs and pushes
133+
- **🔧 Circuit Build** - Compiles Noir circuits and caches artifacts
134+
- **🧪 Circuit Testing** - Runs all circuit tests with Noir toolchain
135+
- **🔐 Proof Generation & Verification** - Full prove/verify cycle validation
136+
- **📝 Contract Compilation** - Compiles Solidity contracts with optimizations
137+
- **⚡ Integration Testing** - End-to-end tests with proof verification on contracts
138+
139+
### **Quality Assurance**
140+
141+
- **Parallel Execution** - Jobs run concurrently for faster feedback
142+
- **Artifact Caching** - Optimized build times with intelligent caching
143+
- **Multi-Environment** - Consistent testing across different Node.js versions
144+
- **Fail-Fast** - Early detection of issues with comprehensive error reporting
145+
146+
## 💡 Understanding the SimpleCounter Example
147+
148+
The **SimpleCounter** demonstrates a complete ZK application workflow:
149+
150+
### **The Circuit** (`circuit/src/main.nr`)
151+
```noir
152+
// Verifies that x + y = result
153+
fn main(x: Field, y: Field, result: pub Field) {
154+
assert(x + y == result);
155+
}
13156
```
157+
158+
### **The Smart Contract** (`contracts/SimpleCounter.sol`)
159+
- Stores a counter value on-chain
160+
- Accepts zero-knowledge proofs to increment the counter
161+
- Verifies proofs using the auto-generated Solidity verifier
162+
- Emits events for successful verifications
163+
164+
### **The Tests** (`test/SimpleCounter.ts`)
165+
- Dynamically generates proofs for different input values
166+
- Tests both valid and invalid proof scenarios
167+
- Demonstrates proof format conversion (binary ↔ JSON)
168+
- Verifies end-to-end integration between circuits and contracts
169+
170+
## 🌐 Deployment
171+
172+
### **Environment Setup**
173+
Configure your deployment environment:
174+
175+
```bash
176+
# Set your private key and RPC URL
177+
npx hardhat vars set SEPOLIA_PRIVATE_KEY
178+
npx hardhat vars set SEPOLIA_URL_RPC
179+
npx hardhat vars set ETHERSCAN_API_KEY
180+
```
181+
182+
### **Deploy to Sepolia**
183+
```bash
184+
yarn contracts:deploy
185+
```
186+
187+
The deployment uses **Hardhat Ignition** for:
188+
- ✅ Reproducible deployments
189+
- ✅ Automatic verification on Etherscan
190+
- ✅ State management and rollback capabilities
191+
- ✅ Multi-network deployment support
192+
193+
## 🧪 Development Workflow
194+
195+
1. **Write your circuit** in `circuit/src/main.nr`
196+
2. **Test circuit logic** with `yarn circuit:test`
197+
3. **Generate verifier contract** with `yarn circuit:solidity_verifier`
198+
4. **Write smart contract tests** in TypeScript
199+
5. **Run full test suite** with `yarn contracts:test`
200+
6. **Deploy and verify** on testnet
201+
202+
## 📚 Learn More
203+
204+
- **[Noir Documentation](https://noir-lang.org/docs)** - Learn zero-knowledge circuit development
205+
- **[Hardhat Documentation](https://hardhat.org/docs)** - Master Ethereum development
206+
- **[Barretenberg](https://github.com/AztecProtocol/aztec-packages/tree/master/barretenberg)** - Understanding the proving system
207+
208+
## 🤝 Contributing
209+
210+
Contributions are welcome! Please ensure:
211+
212+
- Follow conventional commit standards (enforced by our CI)
213+
- Add tests for new features
214+
- Update documentation as needed
215+
- All CI checks pass
216+
217+
## 📄 License
218+
219+
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
220+
221+
---
222+
223+
**Built with ❤️ for the Noir and Ethereum communities**

0 commit comments

Comments
 (0)