Zero-Knowledge Lending with On-Chain Credit Enforcement

Every DeFi lending protocol today is an open book. Your wallet balance, loan size, collateral ratio, interest rate — all of it visible to anyone with a block explorer. This is surveillance infrastructure dressed up as financial infrastructure.

PrivLend proves you don't have to choose between decentralization and privacy.

PrivLend is a fully on-chain, privacy-preserving lending protocol on Aleo. Borrowers prove creditworthiness with a Zero-Knowledge CreditTier record — lenders see the tier (0, 1, or 2), never the identity behind it. Every sensitive loan detail is stored as an encrypted private record inside the borrower's wallet. The chain only ever learns the minimum it needs to enforce the rules.

Traditional DeFi:  "Here is my address, my balance, my loan, my collateral."
PrivLend v8:       "I am creditworthy. Here is the ZK proof."

v8 addresses four critical protocol issues identified by Wave 4 judges:

1. On-Chain Credit Tier Enforcement — Tier 1 requires ≥1 successful repayment, Tier 2 requires ≥3. Enforced via the repayment_count mapping. No more self-asserted tiers.

2. Fund Amount Verification — fund_borrower now asserts amount == loan_principal.get(loan_id). Under/over-funding is rejected on-chain.

3. Collateral Privacy Fix — collateral_locked changed from u64 → bool. Observers can no longer infer the private principal from the public collateral amount.

4. Time-Based Interest + Partial Repayments — Interest accrues proportionally to elapsed blocks: interest = principal × bps × elapsed / (10000 × duration). Partial payments are accepted; the loan stays active until fully cleared.

v8 minimizes information leakage: the public chain sees only boolean flags and counters, never sensitive amounts.

Private-DeFi-Lending/
├── frontend/
│   └── src/
│       ├── components/     # LoanCard, CreditTierCreator, LoanCreationForm, Swap
│       ├── context/        # PrivLendContext — global state & wallet integration
│       ├── pages/          # Dashboard, Borrow, Markets, Portfolio, Swap, Landing
│       ├── services/       # TransactionManager — public tx history via Provable API
│       ├── types/          # TypeScript types mirroring Leo records
│       └── utils/          # AleoService — public mapping reads via REST API
├── privlend/                          # Leo 4.0 Smart Contract
│   ├── src/
│   │   └── main.leo                   # privlend_v8.aleo — full contract source
│   ├── build/
│   │   ├── main.aleo                  # Compiled Aleo bytecode
│   │   ├── abi.json                   # Contract ABI
│   │   └── imports/                   # Compiled dependency programs
│   │       ├── credits.aleo
│   │       └── test_usdcx_stablecoin.aleo
│   └── program.json                   # Leo manifest (version, dependencies)
├── scripts/
│   ├── liquidation-bot.ts             # Polls expired loans, prints liquidate commands
│   └── tsconfig.json                  # TypeScript config for scripts
└── program.json            # Leo 4.0 manifest

┌─────────────────────────────────────────┐
│         React + Vite Frontend           │
│    (MUI, Framer Motion, TypeScript)     │
└──────────────────┬──────────────────────┘
                   │  wallet adapter
┌──────────────────▼──────────────────────┐
│      Shield / Leo / Puzzle Wallet       │
│   (record decryption, ZK proof gen)     │
└──────────────────┬──────────────────────┘
                   │  executeTransaction
┌──────────────────▼──────────────────────┐
│         privlend_v8.aleo                │
│      (Leo 4.0 Smart Contract)           │
└───────────────┬──────────┬─────────────┘
                │          │
   ┌────────────▼──┐  ┌────▼──────────────────┐
   │ Private Records│  │  Public Mappings (v8) │
   │ (encrypted,    │  │  loan_active          │
   │  wallet-only)  │  │  loan_owner           │
   │                │  │  loan_lender          │
   │  Loan          │  │  loan_deadline        │
   │  Collateral    │  │  collateral_locked    │
   │  CreditTier    │  │  loan_principal  (v8) │
   │                │  │  repayment_count (v8) │
   │                │  │  loan_counter         │
   └────────────────┘  └───────────────────────┘

Program: privlend_v8.aleo (Leo 4.0)

record Loan {
    owner:           address,   // borrower
    lender:          address,
    loan_id:         u32,
    principal:       u128,      // USDCx amount
    collateral:      u64,       // microcredits
    tier:            u8,        // 0, 1, or 2
    interest_bps:    u16,       // e.g. 500 = 5%
    start_block:     u32,
    duration_blocks: u32,
    repaid:          u128,      // v8: tracks partial payments
    status:          u8,        // 0=active, 2=repaid
}

record CreditTier {
    owner: address,
    tier:  u8,       // 0=anyone, 1=≥1 repayment, 2=≥3 repayments (v8)
    nonce: field,
}

record Collateral {
    owner:        address,
    loan_id:      u32,
    amount:       u64,
    locked_until: u32,
}

Borrower                          Lender
   │                                │
   ├─── create_credit_tier ─────────┤  (ZK record minted, tier hidden)
   │                                │
   ├─── open_loan ──────────────────┤  (collateral locked, tier verified on-chain)
   │                                │
   │◄─── fund_borrower ─────────────┤  (lender sends exact USDCx principal — verified)
   │                                │
   ├─── repay_loan ─────────────────►  (partial or full payment, time-based interest)
   │    (can repeat)                │
   │                                │
   ├─── repay_loan (final) ─────────►  (collateral released, repayment_count++)
   │                                │
   │         OR (if expired)        │
   │                                │
   │◄─────── liquidate ─────────────┤  (lender claims locked collateral)

• Node.js ≥ 18
• pnpm (or npm/yarn)
• Shield Wallet browser extension (recommended) or Leo Wallet
• Leo 4.0 (for local development)

git clone https://github.com/girume1/Private-DeFi-Lending
cd Private-DeFi-Lending
cd frontend
pnpm install

cp .env.example .env

.env contents:

VITE_PROGRAM_ID=privlend_v8.aleo
VITE_NETWORK=testnet
VITE_API_ENDPOINT=https://api.explorer.provable.com/v2
VITE_USDCX_PROGRAM=test_usdcx_stablecoin.aleo
VITE_CREDITS_PROGRAM=credits.aleo

pnpm dev
# → http://localhost:5173

You'll need two browser profiles or wallets — one for the borrower, one for the lender.

As Borrower:

1. Connect Shield Wallet at https://privlend.vercel.app
2. Get test ALEO from https://faucet.aleo.org
3. Go to Swap → swap some ALEO → USDCx (needed for repayment later) or you can bridge here https://usdcx.aleo.dev/
4. Go to Borrow → click Create Credit Tier → pick tier 0 (tier 1/2 require repayment history)
5. Click New Loan → set principal, collateral (≥ 150%), interest rate, duration, lender address
6. Share the loan ID with your lender

As Lender:

7. Connect a second wallet on Markets page
8. Find the loan by ID → click Fund Borrower → send the exact USDCx principal (v8 verifies on-chain)

Back as Borrower:

9. Go to Portfolio → click Repay → enter payment amount (partial ok in v8)
10. If partial: loan stays active, repaid field updates
11. If full: collateral releases automatically, repayment_count increments (unlocks tier upgrades)

Credit tiers are ZK records with on-chain enforcement. v8 checks repayment_count before issuing tier upgrades.

v8 Change: The open_loan finalize block reads repayment_count.get_or_use(borrower, 0u32) and asserts count >= required_repayments(tier). Tier upgrades are now earned, not self-asserted.

Other ZK chains let you hide a transaction. Aleo lets you prove properties about a transaction without revealing the transaction itself.

PrivLend v8 uses this in a specific way:

• The CreditTier record proves "this person has earned tier 1" without revealing who they are or what loans they've repaid
• The Loan record stores all sensitive terms in the borrower's wallet — the on-chain contract enforces time-based interest arithmetic without ever seeing the plaintext
• The repay_loan function verifies payment > 0 && repaid + payment <= total_due inside the ZK circuit — partial payments work without exposing balances

DeFi can be transparent in logic, private in data. PrivLend v8 is the proof.

• v8: On-chain credit tier enforcement — repayment history gates tier upgrades
• v8: Fund amount verification — fund_borrower rejects mismatched principals
• v8: Collateral privacy fix — collateral_locked stores bool, not raw u64
• v8: Time-based interest + partial repayments — proportional accrual, incremental payments
• v8: Variable collateral ratios — tier 0 = 150%, tier 1 = 135%, tier 2 = 120%
• v8: Liquidation bot — scripts/liquidation-bot.ts polls expired loans and prints liquidation commands
• Private credit scoring — ZK proof of repayment history across multiple loans without revealing loan details
• Recursive proof aggregation — batch multiple loan state updates into a single proof for gas efficiency
• Multi-asset collateral — support additional tokens beyond microcredits
• Mainnet deployment — post-Aleo mainnet launch

scripts/liquidation-bot.ts polls the Aleo testnet for expired loans and prints liquidation candidates.

# Install ts-node if needed
npm install -g ts-node typescript

# Run (dry-run — read only, no transactions sent)
npx ts-node --project scripts/tsconfig.json scripts/liquidation-bot.ts

# Configure via env vars
ALEO_NETWORK=testnet POLL_INTERVAL_MS=60000 npx ts-node --project scripts/tsconfig.json scripts/liquidation-bot.ts

The bot scans all loans, finds any where block.height >= loan_deadline and loan_active == true, and prints the leo execute liquidate command for each. Lenders can copy-paste the command to claim collateral.

PRs welcome. Before submitting:

cd frontend
pnpm lint
pnpm build   # ensure no TypeScript errors

Please open an issue first for significant changes.

MIT — see LICENSE for details.

Built for the Aleo Privacy Buildathon 2026
Proving that financial privacy and decentralization are not a tradeoff.