ZK Leaseback - Financial Covenant Verification

(NOTE: This project is still IN PROGRESS)

A zero-knowledge proof system for verifying financial covenants in leaseback transactions using Noir, Garaga, and Starknet. This application allows companies to prove compliance with financial covenants without revealing sensitive financial data.

Overview

This project demonstrates a privacy-preserving financial verification system with:

• Noir Circuit: Validates financial covenants (debt-to-equity ratio, interest coverage, etc.)
• In-Browser Proving: Generate ZK proofs directly in the browser using Barretenberg
• Starknet Verification: Submit and verify proofs on Starknet blockchain
• Next.js Frontend: Modern web interface for proof generation and verification

Architecture

├── circuits/          # Noir ZK circuit for financial covenant validation
├── contracts/         # Cairo smart contracts for on-chain verification  
├── app/              # Next.js frontend application
└── scripts/          # Setup and utility scripts

Financial Covenants

The system verifies the following financial covenants:

1. Debt-to-Equity Ratio: debt/equity ≤ 2.5
2. Interest Coverage Ratio: EBITDA/interest ≥ 1.5
3. Debt Service Coverage Ratio: cashflow/lease_payment ≥ 1.2
4. Current Ratio: current_assets/current_liabilities ≥ 1.0

Quick Start

Prerequisites

Ensure you have node.js >= 20 installed.

Bun is used for package management, install it with:

make install-bun

For compiling Noir circuits and generating proofs we need specific versions of Aztec packages:

make install-noir
make install-barretenberg

Starknet toolkit comes in a single bundle via asdf (the following command will install it if you don't have it):

make install-starknet

We also need to install a tool for spawning local Starknet chain:

make install-devnet

Finally we need to install Garaga. Make sure you have Python 3.10 in your system. You may also need to start a separate Python virtual environment for this to work. You can do that with python3.10 -m venv garaga-venv && source garaga-venv/bin/activate. Then install with:

If you encounter issues installing Garaga on your operating system, Docker installation is preferred. See the [Docker guide](https://www.notion.so/Steps-to-Run-the-Scaffold-Garaga-Demo-in-Docker-20e8ba8810a480eb8817f89f2168f21f?source=copy_link) for reference.

Note: We need specific versions of Noir, Barretenberg, and Garaga to work well together. If you experience issues with code generation, proving, or verification, first ensure you have the correct package versions.

### E2E Testing & On-Chain Verification

For end-to-end testing with proof generation and on-chain verification:

**Option 1: Docker (Recommended)**
```sh
# Build container (one-time)
docker build -t zk-leaseback .

# Run E2E tests in container
docker run -it -v $(pwd):/app zk-leaseback bash
cd /app/scripts && bun run e2e:dev

See DOCKER_GUIDE.md for complete Docker workflow and Sepolia deployment.

Option 2: Starknet Sepolia Testnet (Local Setup)

# Follow the comprehensive guide
cat SEPOLIA_SETUP.md

# Or use the quick deployment script
cd scripts && chmod +x ../deploy.sh && bash ../deploy.sh

Option 3: Local Devnet

make devnet
cd scripts && bun run e2e:dev

See SEPOLIA_SETUP.md for full setup instructions and DEPLOYMENT_GUIDE.md for deployment steps.

Setup and Run

Option 1: Quick Setup (Recommended)

Run the automated setup script from the project root:

chmod +x scripts/setup-app.sh
./scripts/setup-app.sh

This will:

1. Compile the Noir circuit
2. Generate the verification key
3. Copy circuit artifacts to the app
4. Install app dependencies
5. Setup WASM files for in-browser proving

Then start the development server:

cd app
npm run dev

Option 2: Manual Setup

1. Build the Circuit

cd circuits
nargo compile

The circuit implements financial covenant validation logic. Sample inputs are in Prover.toml for testing.

2. Generate Verification Key

bb write_vk -b ./target/leaseback.json -o ./target/

3. Setup the Next.js App

cd ../app

# Install dependencies
npm install

# Copy circuit artifacts
cp ../circuits/target/leaseback.json public/circuit.json
cp ../circuits/target/vk public/vk.bin

# Copy WASM files for in-browser proving
chmod +x scripts/copy-wasm.sh
./scripts/copy-wasm.sh

# Start development server
npm run dev

Open http://localhost:3000 to use the application.

Option 3: E2E Testing & Verification

For complete proof generation and on-chain verification:

# Install E2E dependencies
cd scripts
bun install

# Option A: Use Starknet Sepolia Testnet (Recommended)
cp .env.example .env
# Update VERIFIER_CONTRACT_ADDRESS in .env with your deployed contract
bun run e2e:dev

# Option B: Use Local Devnet
# First start devnet in another terminal: make devnet
bun run e2e:dev

For detailed Sepolia deployment instructions, see SEPOLIA_SETUP.md.

References

• Scaffold Garaga - Original template
• DOCKER_GUIDE.md - Docker setup and deployment
• SEPOLIA_SETUP.md - Comprehensive Sepolia testnet setup
• DEPLOYMENT_GUIDE.md - Deployment reference guide

Scripts (/scripts)

E2E testing and deployment infrastructure:

• e2e/e2e.ts - Complete end-to-end test orchestration
  • Proof generation from circuit witness
  • On-chain verification via Starknet RPC
  • Support for both devnet and Sepolia testnet
• package.json - E2E dependencies and npm scripts
• deploy.sh - Automated deployment script for Sepolia
• Dockerfile - Complete build environment for CI/CD
• .env.example - Environment configuration template

Circuit Details

Circuit Size

• Gates: ~11,662
• Max Supported: 524,288 gates (2^19)
• Public Inputs: Financial statement root
• Public Outputs: Financial statement root + nullifier hash

Privacy Features

• Financial data remains private (never revealed on-chain)
• Nullifier prevents double-spending/double-factoring
• Merkle tree commitment for financial statements
• Zero-knowledge proof of covenant compliance

Development

Testing the Circuit

cd circuits
nargo test

Regenerating Verifier Contract

After modifying the circuit:

# Recompile circuit
cd circuits
nargo compile

# Regenerate VK
bb write_vk -b ./target/leaseback.json -o ./target/

# Regenerate verifier contract
make gen-verifier

Building for Production

cd app
npm run build
npm start

Troubleshooting

WASM Files Missing

cd app
chmod +x scripts/copy-wasm.sh
./scripts/copy-wasm.sh

Circuit Artifacts Not Found

cp circuits/target/leaseback.json app/circuits/circuit.json
cp circuits/target/vk app/circuits/vk.bin

Proof Generation Fails

• Ensure circuit artifacts are up to date
• Check that WASM files are in app/circuits/wasm/
• Verify input values meet covenant requirements

Technologies

• Noir: Zero-knowledge proof language and compiler
• Barretenberg: Ultra Honk proof system backend
• Garaga: Starknet proof verification library
• Next.js: React framework for the frontend
• Starknet: Layer 2 blockchain for verification
• Cairo: Smart contract language for Starknete verifier contract in contracts/verifier/ based on your circuit.

2. Start Local Devnet

In a separate terminal:

make devnet

3. Setup Account

make accounts-file

4. Declare and Deploy

make declare-verifier
make deploy-verifier

Update the contract address in app/src/components/LeasebackProofForm.tsx:

const contractAddress = "0x..."; // Your deployed contract address

1. Build the app with `bun run build`
1. Finally we can run the app: `bun run dev`

## Useful links

- Noir quickstart https://noir-lang.org/docs/getting_started/quick_start
- Garaga docs https://garaga.gitbook.io/garaga/deploy-your-snark-verifier-on-starknet/noir
- Starknet.js docs https://starknetjs.com/docs/guides/intro
- Starknet quickstart https://docs.starknet.io/quick-start/overview/
- Sncast 101 https://foundry-rs.github.io/starknet-foundry/starknet/101.html
- Cairo book https://book.cairo-lang.org/